home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 501-525 / disk_513 / dkbtrace / dkb212dc.lzh / dkb212.doc < prev    next >
Text File  |  1991-05-04  |  157KB  |  3,693 lines
  1.                         DKBTrace Ray-Tracer,
  2.                           Version 2.12
  3.               "It's free, and it's well worth the price!"
  4.  
  5.  
  6. This program was written by:
  7.  
  8.     David Buck
  9.     22C Sonnet Cres.
  10.     Nepean, Ontario
  11.     Canada, K2H 8W7
  12.  
  13. It has been made freely distributable.  The author retains the
  14. copyright to the program but authorizes free distribution by BBS'es,
  15. networks or by magnetic media.  The distributor may choose to charge
  16. for the cost of the disk but must not sell the software for profit.
  17. Non-profit organizations such as clubs may charge for the software so
  18. long as the price is reasonable (less than $5.00 more than the cost of
  19. the disk) and so long as the buyers are informed that the program is
  20. freely distributable. 
  21.  
  22. The images and data files generated by the raytracer are the property
  23. of the user of the software and may be used for any purpose without
  24. restriction. 
  25.  
  26. The author makes no guarantees or warranties with this program and
  27. claims no responsibility for any damage or loss of time caused by this
  28. program. Bug reports may be sent to the author but the author is under
  29. no obligation to provide bug fixes, features, or any support for this
  30. software. 
  31.  
  32. I would also like to place the following conditions on the use of this program:
  33.  
  34.  1) that it should not be used as part of any commercial package without my
  35.     explicit written consent.
  36.  2) if you make any neat and interesting pictures, please send them to me.
  37.  3) If you make any changes to the source code, please let me know. I'd like
  38.     to see what you've done.
  39.  4) This text file should accompany the program.
  40.  
  41.  
  42. I can be reached on the following BBS'es:
  43.  
  44.     OMX       (613) 731-3419
  45.     Mystic    (613) 731-0088 or (613) 731-6698
  46.     FidoNet   1:163/109.9
  47.     Internet  dbuck@ccs.carleton.ca
  48.     CIS       70521,1371
  49.     "You can call me Ray"   (708) 358-5611
  50.  
  51. Aaron Collins (IBM port) can be reached on the following BBS'es
  52.  
  53.     "You can call me Ray"   (708) 358-5611
  54.  
  55. AAC:  As of July of 1990, there is a Ray-Trace specific BBS in the (708) Area
  56. Code (Chicago suburbia) for all you Traceaholics out there.  The phone number
  57. of this new BBS is (708) 358-5611.  I am Co-Sysop of that board, and David is
  58. a frequent caller.  There is now also a Ray-Trace and Computer-Generated Art
  59. specific SIG on Compuserve, GO COMART.  And now, back to the DOCS... 
  60.  
  61. The GIF file reader was written by Steven A. Bennett.  Here's his copyright
  62. notice:
  63.  
  64.     * DECODER.C - An LZW decoder for GIF
  65.     * Copyright (C) 1987, by Steven A. Bennett
  66.     *
  67.     * Permission is given by the author to freely redistribute and include
  68.     * this code in any program as long as this credit is given where due.
  69.     *
  70.     * In accordance with the above, I want to credit Steve Wilhite, who
  71.     * wrote the code which this is heavily inspired by...
  72.     *
  73.     * GIF and 'Graphics Interchange Format' are trademarks (tm) of
  74.     * Compuserve, Incorporated, an H&R Block Company.
  75.  
  76. The Noise and DNoise functions (used for texturing) were written by
  77. Robert Skinner and used here with his permission. 
  78.  
  79.  
  80.  
  81. This manual is divided into the following sections:
  82.    1) Program Description
  83.    2) Program History and Information
  84.    3) Getting Started
  85.    4) Command Line Parameters
  86.    5) A Tutorial Walkthrough
  87.    6) The Scene Description Language
  88.    7) Displaying the Images
  89.    8) DKBTrace Utilities
  90.    9) How it All Works (or How to Get What You Want)
  91.   10) Common Questions and Answers
  92.   11) Converting Data Files from Versions Prior to 2.10
  93.   12) Handy Hints
  94.   13) Compiling the Code
  95.   14) Porting to Different Platforms
  96.   15) References
  97.   16) Concluding Remarks
  98.  
  99. Some sample worlds and their corresponding images are provided with this
  100. distribution.  To be honest, the images I usually create are dull boring
  101. test files.  Other people, however, have created some really spectacular
  102. images.  Looking at the data files for these will give you some ideas and
  103. help you design your own data files.
  104.  
  105.  
  106.  
  107.  
  108. 1)  Program Description
  109.  
  110.  
  111. This program is a ray tracer written completely in C.  It supports
  112. arbitrary quadric surfaces (spheres, ellipsoids, cones, cylinders,
  113. planes, etc.), constructive solid geometry, and various shading models
  114. (reflection, refraction, marble, wood, and many others).  It also has
  115. special-case code to handle spheres, planes, triangles, and smooth
  116. triangles.  By using these special primitives, the rendering can be
  117. done much more quickly than by using the more general quadrics.  In
  118. order to create pictures with this program, you must describe the
  119. objects in the world.  This description is a text file called
  120. "<filename>.data", and <filename> defaults to "object" if not
  121. specified.  Normally, such files are difficult to write and to read.
  122. In order to make this task easier, the program contains a parser to
  123. read the data file.  It allows the user to easily create complex
  124. worlds from simple components.  Since the parser allows include files,
  125. the user may put the object descriptions into different files and
  126. combine them all into one final image. 
  127.  
  128.  
  129.  
  130. 2)  Program History and Information
  131.  
  132.  
  133. Version 1.2:
  134.     Initial Amiga release.
  135.  
  136. Version 2.0:
  137.     First release Version 2.0 Conversion to the IBM done by Aaron A. Collins
  138.     New textures, Specular and Phong highlighting added by Aaron A. Collins.
  139.     Triangle, Smooth Triangle, Sphere, Plane support added by David Buck
  140.     RAW, IFF and GIF image mapping added by David Buck and Aaron Collins
  141.     Transparency and Fog added by David Buck
  142.     GIF format file reader by Steve Bennett (used with permission)
  143.     New Noise and DNoise functions by Robert Skinner (used with permission)
  144.     TARGA format output file capability added by Aaron A. Collins
  145.     ANSI-C function prototyping for ALL functions,
  146.     Reversal of the order of writing screen data from the original DKB/QRT
  147.        "RAW" file format.
  148.     For IBM's, it has a crude VGA 320x200 by 256 color display rendering
  149.        ability.
  150.  
  151.     Version 2.0 compiles under Turbo-C 2.0 on the IBM P.C. and Lattice C
  152.     5.05 on the Amiga.  The only file which contains the ANSI extensions
  153.     is dkbproto.h, so for non-ANSI compilers, you only need to remove the
  154.     declaration of the parameters in the config.h file and the whole thing
  155.     should compile.  There are several example config.h files for Amiga,
  156.     IBM, and Unix.  The appropriate one should be copied over CONFIG.H,
  157.     and the MAKEFILE should be edited for your particular system and
  158.     compiler configuration before compilation. 
  159.     
  160.     Version 2.0 has a significant difference from prior releases:  Speed!
  161.     The new primitives of SPHERE, PLANE, TRIANGLE, etc. greatly speed up
  162.     tracing.  Another significant speed-up is that world X-Y-Z values
  163.     beyond 10 Million or so are ignored, and ray tracing beyond that
  164.     distance will cease.  This produces 2 minor peculiarities:
  165.  
  166.      1)   A black stripe at the horizon point of Pre-2.0 scene description
  167.           .data files that have "ground" and "sky" planes defined.  The
  168.           planes were traced out to a much greater "infinity" so this effect
  169.           was unnoticeable, prior to version 2.0.
  170.  
  171.      2)   Tiny black pixels in the texture, or "Surface Acne".
  172.  
  173.  
  174.     This is usually caused by rays being refracted or reflected such that
  175.     the ray does not happen to hit any object, and eventually becomes
  176.     black in color as it gets too far away and gets clipped.  This effect
  177.     can be minimized by enclosing the scene with distant "walls",
  178.     "floors", or placing "ocean floors" beneath water, etc.  So far, no
  179.     scenes have required placing such planes behind the camera, unless an
  180.     "environment map" of sorts is desired.  See SKYTEST.DAT for several
  181.     examples of spurious distant planes.  If your "acne" still doesn't go
  182.     away, it may be due to a large pixel sample area and it's accidentally
  183.     picking a point which is just inside the primitive being hit.  This is
  184.     a more tricky problem to solve, and anti-aliasing the image will
  185.     definitely help if this sort of thing occurs. 
  186.  
  187. Version 2.10:
  188.     A few unofficial releases were made between 2.01 and 2.10.  The following
  189.     points capture the major changes:
  190.  
  191.     - Less memory is required for image mapped GIF and IFF files.
  192.     - The output format command-line option was changed to +fx where 'x'
  193.       denotes the output format.
  194.     - The display option +d now takes an optional extra character +dx
  195.       where 'x' is system-dependent.  This allows you to specify the graphics
  196.       mode by a command-line switch.
  197.     - The tokenizing pass has been removed.  It's now called directly by the
  198.       parser.
  199.     - The environment variable DKBOPT is used in addition to the trace.def file
  200.       and the command-line options.
  201.     - The numbers in the data file can now use full scientific notation
  202.       eg. 10.23e-4
  203.     - The +c option was added to continue an aborted trace.
  204.     - You can now colour or texture each component of the CSG's separately.
  205.     - Layered textures implemented (see the section on textures).
  206.     - When using GIF and IFF images for image mapping, you can now indicate that
  207.       specified registers are partially or completely transparent.
  208.     - Textures are now transformed whenever the object or shape they are attached
  209.       to are transformed.
  210.     - The texture CHECKER_TEXTURE has been added.
  211.     - All keywords relating to the appearance of the surface have been made
  212.       illegal in an object definition unless they are inside a TEXTURE block.
  213.     - The "basicshapes.data" file has been split up into shapes.dat, colors.dat,
  214.       and textures.dat.  These files have also been expanded with more useful
  215.       declarations.
  216.     - The -l command-line parameter has been added to support library
  217.       directories.
  218.  
  219. Version 2.11:
  220.     - Quartic surfaces (4th order) added by Alexander Enzmann.
  221.     - Parser now accepts ^Z as a whitespace
  222.     - Keyword END_SMOOTH_TRIANGLE added (previously, END_TRIANGLE was used.)
  223.  
  224. Version 2.12:
  225.     - Bug in smooth triangles fixed to allow them to be scaled and translated.
  226.     - METALLIC texture added.
  227.  
  228. 3)  Getting Started
  229.  
  230. If you've been reading this document diligently until now, you'll probably
  231. want to go in and display some images to see what the raytracer does.
  232. Here's what you need to do:
  233.  
  234.    1) Put the file "sunset.dat" into your current directory.
  235.    2) Make sure the files "colors.dat", "shapes.dat", and "textures.dat"
  236.       are present.
  237.    3) Set up the default parameters.  This can be done by creating a file
  238.       called "trace.def" or by setting the DKBOPT environment variable.
  239.       In either case, use the following line (you may change these defaults
  240.       to suit your system):
  241.  
  242.          -w320 -h400 -v +f +d +p +x -a
  243.  
  244.       Meaning:
  245.          -v    - Don't be verbose, i.e. don't show line numbers during trace.
  246.          +f    - Write an output file in "dump" or "Targa" format (machine
  247.                  specific; IBM default is "Targa", Amiga default is "dump".
  248.          +d    - Display the image while rendering (on some systems, an
  249.                  additional character may follow this option to specify the
  250.                  graphics mode to use for the display).
  251.          -w320 - Make the image 320 pixels wide.
  252.          -h400 - Make the image 400 pixels high.
  253.          +p    - Prompt before exitting to let you look at the picture.
  254.          +x    - Allow exitting with a key hit before the trace is finished.
  255.          -a    - Don't Antialias (Antialiasing smooths out jagged edges).
  256.  
  257.    4) To render a scene, type:
  258.  
  259.          dkbxxx -isunset.dat -osunset.dis
  260.            ^
  261.            |_____ See note below:
  262.  
  263.  
  264.       Meaning:
  265.          dkbxxx - On different systems, the name of the executable may vary.
  266.                  Check to see what it is on your system.  For the Amiga,
  267.                  for example, two versions are supplied: dkb881 and dkbieee
  268.                  for systems with and without a floating-point accelerator.
  269.                  For the IBM, DKB.EXE is the 20286 optimized/uses 80287 math
  270.                  coprocessor version, and DKBNO87.EXE is the plain 8086/no
  271.          8087 math coprocessor version.
  272.  
  273.          -isunset.dat
  274.                - Read the input file "sunset.dat"
  275.  
  276.          -osunset.dis
  277.                - Call the output file "sunset.dis" - this is the usual file
  278.              name extension for "dump" format.  "Targa" format files
  279.          (default for IBM's) generally use the extension ".tga".
  280.  
  281.  
  282.    5) Once the image has been rendered, you must use a post-processor to
  283.       create the final viewable image file (i.e. an IFF or GIF file), unless
  284.       you possess 24-bit display hardware and can view the generated output
  285.       files directly.  The post-processor used depends on your system.  See
  286.       the section "Displaying the Images" for more details on post-processing
  287.       the image.
  288.  
  289. The following section gives a detailed description of the command-line
  290. options.
  291.  
  292.  
  293.  
  294. 4)  Command Line Parameters
  295.  
  296. This program is designed to be run from a command line.  The command-line
  297. parameters may be specified in any order.  Repeated parameters overwrite
  298. the previous values.  Parameters may also be specified in a file called
  299. "trace.def" or by the environment variable "DKBOPT".
  300.  
  301.      -wxxx     width of the picture in pixels
  302.                (On the Amiga, use 320 for full-sized pictures)
  303.      -hxxx     height of the picture in pixels
  304.                (On the Amiga, use 400 for full-sized pictures)
  305.  
  306.      +v        verbose option - print out the scan line number.
  307.      -v        disable verbose option
  308.  
  309.      +f[x]     produce an output file
  310.      -f        don't produce an output file
  311.  
  312.                If the +f option is used, the ray tracer will produce an
  313.                output file of the picture.  This output file describes each
  314.                pixel with 24 bits.  Currently, three formats of output files
  315.                are supported:
  316.  
  317.                   +fd    (default) - Dump format (QRT-style)
  318.                   +fr              - Raw format - three files for R, G and B.
  319.                   +ft              - Uncompressed Targa-24 format
  320.  
  321.  
  322.                Normally, a post-processor is required to create the final
  323.                finished image from the data file.  See the section on
  324.                "Displaying the Images" for details.
  325.  
  326.  
  327.      +d[x]     display the picture while tracing
  328.      -d        don't display the picture while tracing
  329.  
  330.                If the +d option is used, then the picture will be displayed
  331.                while the program performs the ray tracing.  On most systems,
  332.                this picture is not as good as the one created by the post-
  333.                processor because it does not try to make optimum choices for
  334.                the colour registers.
  335.  
  336.  
  337.                Depending on the system, a letter may follow the +d option to
  338.                specify the graphics mode to use.
  339.  
  340.                   All systems:
  341.                     +d      Default Format (same as +d0)
  342.  
  343.                   Amiga:
  344.                     +d0     Ham format
  345.                     +dE     Ham-E format
  346.  
  347.                   IBM:
  348.                     +d0     Autodetect (S)VGA type
  349.                     +d1     Standard VGA 320x200
  350.                     +d2     Simulated SVGA 360x480
  351.                     +d3     Tseng Labs 3000 SVGA 640x480
  352.                     +d4     Tseng Labs 4000 SVGA 640x480
  353.                     +d5     AT&T VDC600 SVGA 640x400
  354.                     +d6     Oak Technologies SVGA 640x480
  355.                     +d7     Video 7 SVGA 640x480
  356.                     +d8     Video 7 Vega (Cirrus) VGA 360x480
  357.                     +d9     Paradise SVGA 640x480
  358.                     +dA     Ahead Systems Ver. A SVGA 640x480
  359.                     +dB     Ahead Systems Ver. B SVGA 640x480
  360.                     +dC     Chips & Technologies SVGA 640x480
  361.                     +dD     ATI SGVA 640x480
  362.                     +dE     Everex SVGA 640x480
  363.                     +dF     Trident SVGA 640x480
  364.                     +dG     VESA Standard SVGA Adapter 640x480
  365.  
  366.  
  367.      +p        wait for prompt (IBM: beep and pause) before quitting
  368.      -p        finish without waiting
  369.  
  370.                The +p option makes the program wait for a carriage return
  371.                before exitting (and closing the graphics screen).  This gives
  372.                you time to admire the final picture before destroying it. 
  373.  
  374.  
  375.   -ifilename   set the input filename
  376.   -ofilename   set output filename
  377.  
  378.                If your input file is not "Object.dat", then you can use -i
  379.                to set the filename.  The default output filename will be
  380.                "data.dis" for dump mode, "data.red", "data.grn" or "data.blu"
  381.                for raw mode, and "data.tga" for Targa mode.  If you want a
  382.                different output file name, use the -o option.
  383.  
  384.                (on IBM's, the default extensions for raw mode are ".r8",
  385.                ".g8", and ".b8" to conform to PICLAB's "raw" format).
  386.  
  387.      +a[xxx]   anti-alias - xxx is an optional tolerance level (default 0.3)
  388.      -a        don't anti-alias
  389.  
  390.                The +a option enables adaptive anti-aliasing.  The number
  391.                after the +a option determines the threshold for the anti-
  392.                aliasing.  If the colour of a pixel differs from its neighbor
  393.                (to the left or above) by more than the threshold, then the
  394.                pixel is subdivided and super-sampled.
  395.  
  396.                If the anti-aliasing threshold is 0.0, then every pixel is
  397.                supersampled.  If the threshold is 1.0, then no anti-aliasing
  398.                is done.  Good values seem to be around 0.2 to 0.4.
  399.  
  400.                The super-samples are jittered to introduce noise and make the
  401.                pictures look better.  Note that the jittering "noise" is non-
  402.                random and repeatable in nature, based on an object's 3-D
  403.                orientation in space.  Thus, it's okay to use anti-aliasing for
  404.                animation sequences, as the anti-aliased pixels won't vary and
  405.                flicker annoyingly from frame to frame.
  406.            
  407.      +x        allow early exit by hitting any key (IBM only)
  408.      -x        lock in trace until finished        (IBM only)
  409.  
  410.                On the IBM, the -x option disables the ability to abort the
  411.                trace by hitting a key.  If you are unusually clumsy or have
  412.                CATS that stomp on your keyboard (like I do - AAC :-)), you
  413.                may want to use it.  If you are writing a file, the system
  414.                will recognize ^C at the end of line if the system "BREAK"
  415.                is "ON".  If you aren't writing a file, you won't be able to
  416.                abort the trace until it's done.
  417.  
  418.                This option was meant for big, long late-nite traces that take
  419.                ALL night (or longer!), and you don't want them interrupted by
  420.                anything less important than a natural disaster such as hur-
  421.                ricane, fire, flood, famine, etc.
  422.  
  423.      -bxxx     use an output file buffer of xxx kilobytes.
  424.                (if 0, flush the file on every line - this is the default)
  425.  
  426.                The -b option allows you to assign large buffers to the output
  427.                file.  This reduces the amount of time spent writing to the
  428.                disk and prevents unnecessary wear (especially for floppies). 
  429.                If this parameter is zero, then as each scanline is finished,
  430.                the line is written to the file and the file is flushed.  On
  431.                most systems, this operation insures that the file is written
  432.                to the disk so that in the event of a system crash or other
  433.                catastrophic event, at least part of the picture has been
  434.                stored properly on disk.
  435.  
  436.      +c        Continue Rendering
  437.  
  438.                If, for some reason, you abort a raytrace while it's in progress
  439.                or if you used the -exxx option (below) to end the raytrace
  440.                prematurely, you can use the +c option to continue the raytrace
  441.                when you get back to it.  This option reads in the previously
  442.                generated output file, displays the image to date on the screen,
  443.                then proceeds with the raytracing.  In many cases, this feature
  444.                can save you a lot of rendering time when things go wrong.
  445.  
  446.                (If you want to impress your friends with the speed of your
  447.                computer, take an image you've already rendered and use +c
  448.                in the command-line.  It renders REAL fast that way!  :-)
  449.  
  450.      -sxxx     start tracing at line number xxx.
  451.      -exxx     end tracing at line number xxx.
  452.  
  453.                The -s option allows you to start rendering an image starting
  454.                from a specific scan line.  This is useful for rendering part
  455.                of a scene to see what it looks like without having to render
  456.                the entire scene from the top.  Alternatively, you can render
  457.                groups of scanlines on different systems and concatenate them
  458.                later.  WARNING: If you are merging output files from different
  459.                systems, make sure that the random number generators are the
  460.                same.  If not, the textures from one will not blend in with the
  461.                textures from the other.  There is an example of a standard
  462.                ANSI "C" random number generator in the file IBM.C.  Cut it
  463.                out and paste it into your machine-specific .C file if you
  464.                plan to try "distributed processing" and are not sure if you
  465.                need this standardization.
  466.  
  467.                The -s option has no effect when continuing a raytrace using
  468.                the +c option.  The renderer will figure out where to restart.
  469.  
  470.      -qx       rendering quality
  471.  
  472.                The -q option allows you to specify the image rendering quality,
  473.                for quickly rendering images for testing.  The parameter can
  474.                range from 0 to 9.  The values correspond to the following
  475.                quality levels:
  476.  
  477.                0,1  Just show colours.  Ambient lighting only.
  478.                2,3  Show Diffuse and Ambient light
  479.                4,5  Render shadows
  480.                6,7  Create surface textures
  481.                8,9  Compute reflected, refracted, and transmitted rays.
  482.  
  483.                The default is -q9 (maximum quality) if not specified.
  484.  
  485.                You may specify the default parameters by modifying the file
  486.                "trace.def" which contains the parameters in the above format. 
  487.                This filename contains a complete command line as though you 
  488.                had typed it in, and is processed before any options supplied
  489.                on the command line are recognized.
  490.  
  491.  
  492.      -lpath    The -l option may be used to specify a "library" pathname to
  493.                look into for data files to include or for images.  Up to 10
  494.                -l options may be used to specify a search path.  The home
  495.                (current) directory will be searched first followed by the
  496.                indicated library directories in order.
  497.  
  498.      +z        The +z option is an undocumented feature.  You will not see any
  499.                references to it in this or any other documentation file for
  500.                DKBTrace.  In fact, no other section of the document will even
  501.                admit that it was mentioned here. If you really want to know
  502.                what it does, then you will have to look into the source code
  503.                (trace.c) and read the comment just above the +z option that
  504.                says "Turn on debugging print statements."  The full purpose
  505.                of this option will, therefore, be left as an exercise for
  506.                the reader, but believe me - it's nothing terribly exciting.
  507.  
  508.                (For those people who run the raytracer on super-fast systems
  509.                and want to slow it down, you may try this option. :-)
  510.  
  511.  
  512.  
  513. 5)  A Tutorial Walkthrough
  514.  
  515.  
  516. This section, is designed to get you up and running designing your own
  517. pictures without all the nit-picky details.  Once you've made a few
  518. of your own data files, you'll probably want to advance to the next
  519. section to fill in the gaps.
  520.  
  521. 5.1)    The First Image
  522.  
  523. Let's get right to the meat of the matter and create the data file for a
  524. simple picture.  Since raytracers thrive on spheres, that's what we'll render
  525. first.
  526.  
  527. First we have to create a viewpoint to tell the computer where our camera is
  528. and where it's looking.  To do this, we use 3D coordinates.  The usual
  529. coordinate system for DKBTrace has Y pointing up, X pointing to the right, and
  530. Z pointing into the screen as follows:
  531.  
  532.  
  533.                 ^Y
  534.                 |
  535.                 |   /Z
  536.                 |  /
  537.                 | /
  538.                 |/       X
  539.                 |-------->
  540.  
  541.  
  542.  
  543. Using your personal favorite text editor (i.e., user interface), create a file
  544. called "picture1.dat".  Now, type in the following (note:  The input is case
  545. sensitive, so be sure to get capital and lowercase letters correct):
  546.  
  547.       INCLUDE "colors.dat"
  548.       INCLUDE "shapes.dat"
  549.       INCLUDE "textures.dat"
  550.  
  551.       VIEW_POINT
  552.          LOCATION  <0 0 0>
  553.          DIRECTION <0 0 1>
  554.          UP        <0 1 0>
  555.          RIGHT     <1.33333 0 0>
  556.       END_VIEW_POINT
  557.  
  558.  
  559. The first INCLUDE statement reads in definitions for various useful colours.
  560. (Being a proud Canadian, I spell colour the proper way with a "u".  To avoid
  561. confusing the rest of the world, however, I've set up the raytracer to allow
  562. either spelling of the word.)
  563.  
  564. The second and third include statements read in some useful shapes and textures
  565. respectively.  When you get a chance, have a look through them to see
  566. but a few of the many possible shapes and textures available.
  567.  
  568. Include files may be nested, if you like.  The total pre-defined number of
  569. INCLUDE'd files (nested or not) per scene is 10.
  570.  
  571. Filenames specified in the INCLUDE statements will be searched for in the home
  572. (current) directory first, and if not found, will then be searched for in
  573. directories specified by any "-l" (library path) options active.  This would
  574. facilitate keeping all your "include" (.inc) files, shapes.dat, colors.dat,
  575. and textures.dat in an "include" subdirectory, and giving an "-l" option on
  576. the command line to where your library of include files are.
  577.  
  578.  
  579. This viewpoint declaration puts our camera at the center of the universe
  580. (LOCATION <0 0 0>) pointing into the Z direction (DIRECTION <0 0 1>) and with
  581. the camera being held upright (UP <0 1 0>).  The final term compensates for
  582. the aspect ratio of the screen (RIGHT <1.33333 0 0>).  If your computer has
  583. square pixels, you may want to change this to "RIGHT <1.0 0 0>".  For details
  584. on exactly how the camera works, see the section "How it All Works". 
  585.  
  586.  
  587. Now, let's place a red sphere into the world:
  588.  
  589.       OBJECT
  590.          SPHERE <0 0 3> 1 END_SPHERE
  591.          TEXTURE
  592.             COLOUR Red
  593.          END_TEXTURE
  594.       END_OBJECT
  595.  
  596. This sphere is 3 units away from the camera and has a radius of 1.  Note that
  597. any parameter that changes the appearance of the surface (as opposed to the
  598. shape of the surface) is called a texture parameter and MUST be placed into a
  599. TEXTURE-END_TEXTURE block.  In this case, we are just setting the colour.
  600.  
  601. One more detail - we need a light source:
  602.  
  603.       OBJECT
  604.          SPHERE <0 0 0> 1 END_SPHERE
  605.          TEXTURE
  606.             COLOUR White
  607.          END_TEXTURE
  608.          TRANSLATE <2 4 -3>     {This is 2 units to our right, 4 units above,}
  609.                                 {and 3 units behind our camera.}
  610.          LIGHT_SOURCE
  611.          COLOUR White
  612.       END_OBJECT
  613.  
  614.  
  615. (Note:  For light sources, ALWAYS declare them to be centered at the origin
  616. <0 0 0>, then use TRANSLATE to put them where you want.  If you don't do this,
  617. the light source won't work right. We must also specify the colour of the
  618. light source OUTSIDE the TEXTURE block because the renderer doesn't want to
  619. work out the whole surface colour just to get the colour of the light it
  620. emits.)
  621.  
  622. That's it!  Close the file and render a small picture of it:
  623.  
  624.       trace -w80 -h100 -f -ipicture1.dat
  625.  
  626. On the IBM, the command line would be:
  627.  
  628.       dkb -w80 -h50 -f -ipicture1.dat
  629.  
  630. (Or "dkbno87 (etc.)" if you have an 8086/8088 system or no math co-processor).
  631.  
  632. 5.2)    Phong Highlights
  633.  
  634. You've now rendered your first picture.  I know you want to run out and show
  635. all your friends how amazing your computer is to be able to generate such an
  636. incredible picture, but just wait a few minutes - you ain't seen nothin' yet.
  637. (For those people who complained that the picture took too long to draw, just
  638. wait - you ain't seen nothin' yet, either...)
  639.  
  640. Let's add a nice little specular highlight (shiny spot) to the sphere.  It
  641. gives it that neat "computer graphics" look.  Change the definition of the
  642. sphere to this:
  643.  
  644.       OBJECT
  645.          SPHERE <0 0 3> 1 END_SPHERE
  646.          TEXTURE
  647.             COLOUR Red
  648.             PHONG 1.0
  649.          END_TEXTURE
  650.       END_OBJECT
  651.  
  652. Now render this.  In all seriousness, the PHONG highlight does add a lot of
  653. credibility to the picture.  You'll probably want to use it in many of your
  654. pictures.
  655.  
  656. 5.3)    Textures
  657.  
  658. One of the really nice features of this raytracer is its sophisticated
  659. textures.  Change the definition of our sphere to the following and then
  660. re-render it:
  661.  
  662.       OBJECT
  663.          SPHERE <0 0 3> 1 END_SPHERE
  664.          TEXTURE
  665.             Dark_Wood
  666.             SCALE <0.2 0.2 0.2>
  667.             PHONG 1.0
  668.          END_TEXTURE
  669.       END_OBJECT
  670.  
  671.  
  672. The textures are set up by default to give you one "feature" across a sphere
  673. of radius 1.0.  A "feature" is roughly defined as a colour transition.  For
  674. example, a wood texture would have one band on a sphere of radius 1.0.  By
  675. scaling the wood by <0.2 0.2 0.2>, we shrink the texture to give us about five
  676. bands. Please note that this is not a hard and fast rule.  It's only meant to
  677. give you a rough idea for the scale to use for a texture.  Don't start
  678. reporting problems if you get three bands instead of five.  This rule of thumb
  679. just puts you in the ballpark.
  680.  
  681. One note about the SCALE operation.  You can magnify or shrink along each
  682. direction separately.  The first term tells how much to magnify or shrink in
  683. the left-right direction.  The second term controls the up-down direction and
  684. the third term controls the front-back direction.
  685.  
  686. I encourage you to look through the "textures.dat" file to see what textures
  687. are defined there and try them out.  Some of them are quite spectacular.
  688.  
  689. 5.4)    Other Shapes
  690.  
  691. So far, we've just defined spheres.  There are several other kinds of shapes
  692. that can be rendered by DKBTrace.  Let's try one out with a computer graphics
  693. standard - a checkered floor.  Add the following object to your .dat file:
  694.  
  695.       OBJECT
  696.          PLANE <0.0 1.0 0.0> -1.0 END_PLANE
  697.          TEXTURE
  698.             CHECKER
  699.                COLOUR RED 1.0
  700.                COLOUR BLUE 1.0
  701.          END_TEXTURE
  702.       END_OBJECT
  703.  
  704.  
  705. The object defined here is an infinite plane.  The vector <0.0 1.0 0.0> is the
  706. surface normal of the plane (i.e., if you where standing on the surface, the
  707. normal points straight up.)  The number afterward is the distance that the
  708. plane is displaced along the normal - in this case, we move the floor down one
  709. unit so that the sphere (radius 1) is resting on it.  The checker texture
  710. specifies the two colours to use in the checker pattern.
  711.  
  712. Looking at the floor, you'll notice that the wooden ball casts a shadow on the
  713. floor.  Shadows are calculated accurately (well, almost - more later) by the
  714. raytracer.
  715.  
  716.  
  717. Another kind of shape you can use is called a quadric surface.  To be totally
  718. honest, the shapes you've been using so far have been quadrics.  Spheres and
  719. planes are types of quadric surfaces.  There are many other quadric surfaces
  720. however.  These are all described by a certain kind of mathematical formula
  721. (see the section on Quadrics in the next chapter).  They include cylinders,
  722. cones, paraboloids (like a satellite dish), hyperboloids (saddle-shaped) and
  723. ellipsoids as well as the spheres and planes we've used so far.
  724.  
  725. All quadrics except for ellipsoids and spheres are infinite in at least one
  726. direction.  For example, a cylinder has no top or bottom - it goes to infinity
  727. at each end.  Quadrics all have one common feature - if you draw any straight
  728. line through a quadric, it will hit the surface at most twice.  A torus
  729. (donut), for example, is not a quadric since a line can hit the surface up to
  730. four times going through.
  731.  
  732. Enough talk - let's render one of these "quadrics"...  While we're at it,
  733. we'll add a few features to the surface.  Add the following definition to your
  734. .dat file:
  735.  
  736.       OBJECT
  737.          QUADRIC Cylinder_Y END_QUADRIC
  738.          TEXTURE
  739.             COLOUR GREEN 0.5
  740.             REFLECTION 0.5
  741.          END_TEXTURE
  742.          SCALE <0.4  0.4  0.4>
  743.          TRANSLATE <2 0 5>
  744.       END_OBJECT
  745.  
  746.  
  747. This object is a cylinder along the Y (up-down) axis.  It's green in colour
  748. and has a mirrored surface (hence the reflection of 0.5) this means that half
  749. the light coming from the sphere is reflected from other objects in the room.
  750. A reflection of 1.0 is a perfect mirror.
  751.  
  752. The object has been shrunk by scaling it by <0.4 0.4 0.4>.  Note that since
  753. the cylinder is infinite along the Y axis, the middle term is kind of
  754. pointless.  One four tenths of infinity is still infinity.  (Don't use 0,
  755. though.  That will definitely cause a fatal crash!)  Finally, the cylinder has
  756. been moved back and to the right so you can see it more clearly.
  757.  
  758. 5.5)    Constructive Solid Geometry
  759.  
  760. The shapes we've talked about so far are nice, but not terribly useful on
  761. their own for making realistic scenes.  It's hard to make interesting objects
  762. when you're limited to spheres, infinite cylinders, infinite planes, and so
  763. forth.  
  764.  
  765. Constructive Solid Geometry (CSG) is a technique for taking these simple
  766. building blocks and combining them together.  You can use a cylinder to bore a
  767. hole through a sphere.  You can use planes to cap cylinders and turn them into
  768. flat circular disks (that are no longer infinite).
  769.  
  770. Before getting into CSG, however, let me talk about inside and outside.  Every
  771. primitive (except triangles - I'll talk about this later) divides the world
  772. into two regions.  One region is inside the surface and one is outside.  So,
  773. given any point in space, you can say it's either inside or outside any
  774. particular primitive object (well, it could be exactly on the surface, but
  775. usually numerical inaccuracies will put it to one side or the other).  Even
  776. planes have an inside and an outside.  By definition, the surface normal of
  777. the plane points towards the outside of the plane.  (For a simple floor, for
  778. example, the space above the floor is "outside" and the space below the floor
  779. is "inside".  For simple floors this in unimportant, but for planes as parts
  780. of CSG's it becomes much more important).
  781.  
  782. CSG uses the concepts of inside and outside to combine shapes together.  Take
  783. the following situation:
  784.  
  785. Note: The diagrams shown here demonstrate the concepts in 2D and are indended
  786.       only as an analogy to the 3D case.  Note that the triangles supported by
  787.       DKBTrace cannot be used in CSG (except for unions) since they have no
  788.       inside and outside.
  789.  
  790.   * = Shape A
  791.   % = Shape B
  792.  
  793.                      *  0
  794.                     * *    %
  795.                    *   *  % %
  796.                   *     *%   %
  797.                  *  1   %*    %
  798.                 *      %  * 2  %
  799.                *      % 3  *    %
  800.               *******%*******    %
  801.                     %             %
  802.                    %%%%%%%%%%%%%%%%%
  803.  
  804.  
  805. There are three CSG operations you can use:
  806.  
  807.    1) UNION A B END_UNION
  808.         A point is inside the union if it is inside A OR it's inside B
  809.         (or both).  This gives an "additive" effect to the component
  810.         objects:
  811.  
  812.                      *
  813.                     * *    %
  814.                    *   *  % %
  815.                   *     *%   %
  816.                  *  1       2 %
  817.                 *       3      %
  818.                *                %
  819.               *******%           %
  820.                     %             %
  821.                    %%%%%%%%%%%%%%%%%
  822.  
  823.  
  824.    2) INTERSECTION A B END_INTERSECTION
  825.         A point is inside the intersection if it's inside both A AND B.  This
  826.         "logical AND's" the shapes and gets the common part, most useful for
  827.         "clipping" infinite shapes off, etc:
  828.  
  829.  
  830.                         %*
  831.                        %  *
  832.                       % 3  *
  833.                      %*******
  834.  
  835.    3) DIFFERENCE A B END_DIFFERENCE
  836.         A point is inside the difference if it's inside A but not inside B.
  837.         The results is a "subtraction" of the 2nd shape from the first shape:
  838.  
  839.  
  840.                      *
  841.                     * *
  842.                    *   *
  843.                   *     *
  844.                  *  1   %
  845.                 *      %
  846.                *      %
  847.               *******%
  848.  
  849. Let's give a concrete example by drilling a yellow hole through our sphere.
  850. Go to the definition of the sphere and change it to read the following:
  851.  
  852.  
  853.       OBJECT
  854.          DIFFERENCE
  855.             SPHERE <0 0 3> 1 END_SPHERE
  856.             QUADRIC
  857.                Cylinder_Z
  858.                SCALE <0.2 0.2 0.2>
  859.                COLOUR Yellow
  860.             END_QUADRIC
  861.          END_DIFFERENCE
  862.          TEXTURE
  863.             Dark_Wood
  864.             SCALE <0.2 0.2 0.2>
  865.             PHONG 1.0
  866.          END_TEXTURE
  867.       END_OBJECT
  868.  
  869. One more point about CSG operations.  You can flip a shape inside-out by
  870. putting the keyword INVERSE into the shape's definition.  This keyword will
  871. not change the appearance of the shape unless you're using CSG.  In the case
  872. of CSG, it gives you more flexibility.  For example:
  873.  
  874.    INTERSECTION B A-INVERSE END_INTERSECTION
  875.  
  876.                    
  877.                            %
  878.                           % %
  879.                          %   %
  880.                          *    %
  881.                           * 2  %
  882.                            *    %
  883.                      %*******    %
  884.                     %             %
  885.                    %%%%%%%%%%%%%%%%%
  886.  
  887. (Note that a DIFFERENCE is really just an INTERSECTION of one shape with the
  888. INVERSE of another.  This happens to be how DIFFERENCE is actually implemented
  889. in the code.)
  890.  
  891. 5.6)    Advanced Textures
  892.  
  893. The textures available in DKBTrace are 3D solid textures.  This means that the
  894. texture defines a colour for any 3D point in space.  Just like a real block of
  895. marble or wood, there is colour all through the block - you just can't see it
  896. until you carve away the wood or marble that's in the way.  Similarly, with a
  897. 3D solid texture, you don't see all the colours in the texture - you only see
  898. the colours that happen to be visible at the surface of the object.
  899.  
  900. As you've already seen, you can scale, translate, and rotate textures.  In
  901. fact, you could make an animation in which the objects stay still and the
  902. textures translate and rotate through the object.  The effect would be like
  903. watching a time-lapse film of a cloudy sky - the clouds would not only move,
  904. but they would also change shape smoothly.
  905.  
  906. Often, textures are perturbed by noise.  This "turbulence" distorts the
  907. texture so it doesn't look quite so perfect.  Try changing the sphere in the
  908. above example to have the following texture:
  909.  
  910.          TEXTURE
  911.             Dark_Wood
  912.             TURBULENCE 0.0
  913.             SCALE <0.2 0.2 0.2>
  914.             PHONG 1.0
  915.          END_TEXTURE
  916.  
  917. When you compare this with the original image, you'll see that the pattern is
  918. much more boring.
  919.  
  920. Finally, many textures use colour maps.  A colour map translates a number
  921. between 0.0 and 1.0 into a colour.  The number typically represents the
  922. distance into a vein of colour - the further into the vein you get, the more
  923. the colour changes.  Here's a typical colour map.  Try this out on the sphere
  924. defined above by changing the definition to this:
  925.  
  926.  
  927.       OBJECT
  928.          SPHERE <0 0 3> 1 END_SPHERE
  929.          TEXTURE
  930.             WOOD
  931.             SCALE <0.2 0.2 0.2>
  932.             COLOUR_MAP
  933.                 [0.0 0.3  COLOUR Red   COLOUR Green]
  934.                 [0.3 0.6  COLOUR Green COLOUR Blue]
  935.                 [0.6 1.01 COLOUR Blue  COLOUR Red]
  936.             END_COLOUR_MAP
  937.             PHONG 1.0
  938.          END_TEXTURE
  939.       END_OBJECT
  940.  
  941.  
  942. This means that as the texture enters into a vein of wood, it changes colour
  943. smoothly from red to green, from green to blue, and from blue to red again.
  944. As it leaves the vein, the transition occurs in reverse.  (Since there is no
  945. turbulence on the wood by default, the veins of colour should show up quite
  946. well.)
  947.  
  948. You can get more "bang for your buck" from textures by using ALPHA properties
  949. of colour.  Every colour you define in DKBTrace is a combination of red,
  950. green, blue and alpha.  The red, green and blue are simple enough.  The alpha
  951. determines how transparent that colour is.  A colour with an alpha of 1.0 is
  952. totally transparent.  A colour with an alpha of 0.0 is totally opaque.  Here's
  953. a neat texture to try:
  954.  
  955.  
  956.    TEXTURE
  957.       TURBULENCE 0.5
  958.       BOZO
  959.       COLOUR_MAP
  960.           { transparent to transparent }
  961.           [0.0 0.6   COLOUR RED 1.0 GREEN 1.0 BLUE 1.0 ALPHA 1.0
  962.                      COLOUR RED 1.0 GREEN 1.0 BLUE 1.0 ALPHA 1.0]
  963.  
  964.           { transparent to white }
  965.           [0.6 0.8   COLOUR RED 1.0 GREEN 1.0 BLUE 1.0 ALPHA 1.0
  966.                      COLOUR RED 1.0 GREEN 1.0 BLUE 1.0]
  967.  
  968.           { white to grey }
  969.           [0.8 1.001 COLOUR RED 1.0 GREEN 1.0 BLUE 1.0
  970.                      COLOUR RED 0.8 GREEN 0.8 BLUE 0.8]
  971.       END_COLOUR_MAP
  972.       SCALE <0.4  0.08  0.4>
  973.    END_TEXTURE
  974.  
  975. This is my (famous) cloud texture.  It creates white clouds with grey linings.
  976. The texture is transparent in the places where the clouds disappear so you can
  977. see through it to the objects that are behind.
  978.  
  979. Now for one more feature which is new for 2.10 (hold onto your hats!)  You can
  980. now layer textures one on top of another to create more sophisticated textures.
  981. For example, suppose I want a wood-coloured cloudy texture.  What I do is put
  982. the wood texture down first followed by my cloud texture.  Wherever the cloud
  983. texture is transparent, the wood texture shows through.  Change your sphere to
  984. the following and you'll see.
  985.  
  986.  
  987.       OBJECT
  988.          SPHERE <0 0 3> 1 END_SPHERE
  989.          TEXTURE        { This is the wood texture we used earlier. }
  990.             Dark_Wood
  991.             TURBULENCE 0.0
  992.             SCALE <0.2 0.2 0.2>
  993.             PHONG 1.0
  994.          END_TEXTURE
  995.          TEXTURE        { This is the cloud texture we just defined. }
  996.             TURBULENCE 0.5
  997.             BOZO
  998.             COLOUR_MAP
  999.                 { transparent to transparent }
  1000.                 [0.0 0.6   COLOUR RED 1.0 GREEN 1.0 BLUE 1.0 ALPHA 1.0
  1001.                            COLOUR RED 1.0 GREEN 1.0 BLUE 1.0 ALPHA 1.0]
  1002.       
  1003.                 { transparent to white }
  1004.                 [0.6 0.8   COLOUR RED 1.0 GREEN 1.0 BLUE 1.0 ALPHA 1.0
  1005.                            COLOUR RED 1.0 GREEN 1.0 BLUE 1.0]
  1006.       
  1007.                 { white to grey }
  1008.                 [0.8 1.001 COLOUR RED 1.0 GREEN 1.0 BLUE 1.0
  1009.                            COLOUR RED 0.8 GREEN 0.8 BLUE 0.8]
  1010.             END_COLOUR_MAP
  1011.             SCALE <0.4  0.08  0.4>
  1012.          END_TEXTURE
  1013.       END_OBJECT
  1014.  
  1015. Each successive texture is layered on top of the previous textures.  In the
  1016. places where you can see through the upper texture, you see through to the
  1017. lower textures.
  1018.  
  1019.  
  1020. 5.7)    Walk-through Wrap-up
  1021.  
  1022. In this walk-through, I've only tried to show the highlights of the raytracer
  1023. without getting into all possible options and features.  To get all of those,
  1024. you'll have to read through the following section on the Object Description
  1025. Language.  Hopefully it will be fairly straight forward now that you have a
  1026. feel for the language and how it works.  Hopefully you'll find that the
  1027. textual interface provided by DKBTrace isn't quite as scary as people think at
  1028. first.
  1029.  
  1030.  
  1031.  
  1032. 6)  The Scene Description Language
  1033.  
  1034. The Scene Description Language allows the user to describe the world in a
  1035. readable and convenient way.
  1036.  
  1037. The language delimits comments by the left and right braces ({ and }). Nested
  1038. comments are allowed, but no sane person uses them anyway, right?
  1039.      
  1040. The language allows include files to be specified by placing the line:
  1041.  
  1042.     INCLUDE "filename"
  1043.  
  1044. at any point in the input file (Include files may be nested).  The filename
  1045. must be enclosed in double quotes and may be up to 40 characters long,
  1046. including the two double-quote (") characters.  You may have at most 10
  1047. INCLUDE'd files per scene trace, whether nested or not.
  1048.  
  1049.  
  1050.  
  1051. 6.1)    The Basic Data Types
  1052.  
  1053.      There are several basic types of data:
  1054.  
  1055. 6.1.1)  Float
  1056. Floats are represented by an optional sign (-), some digits, an optional
  1057. decimal point, and more digits.  Version 2.10 now supports the "e" notation
  1058. for exponents.  The following are valid floats:
  1059.  
  1060.      1.0  -2.0  -4  34  3.4e6 2e-5
  1061.  
  1062. 6.1.2)  Vector
  1063. Vectors are arrays of three floats.  They are bracketed by angle brackets
  1064. ( < and > ), and the three terms usually represent x, y, and z.  For example:
  1065.  
  1066.      < 1.0  3.2  -5.4578 >
  1067.  
  1068. Vectors typically refer to relative points.  For example, the vector:
  1069.  
  1070.      <1 2 3>
  1071.  
  1072. means the point that's 1 unit to the right, 2 units up, and 3 units in front.
  1073. "Of what?" you ask?  Well, usually it's relative to the center of the
  1074. "universe" at <0 0 0>.
  1075.  
  1076. In a few places here and there, vectors are used as a convenient notation but
  1077. don't represent a point in space. This is the case for the transformations
  1078. TRANSLATE, ROTATE, and SCALE.
  1079.  
  1080.    TRANSLATE <x y z>       - move the object x units to the right,
  1081.                              y units up, and z units away from us.
  1082.  
  1083.    SCALE     <xs ys zs>    - scale the object by xs units in the left/right
  1084.                              direction, ys units in the up/down direction
  1085.                              and zs units in the front/back direction.
  1086.  
  1087.    ROTATE    <xr yr zr>    - rotate the object xr degrees about the X axis,
  1088.                              then yr degrees about the Y axis, then zr degrees
  1089.                              about the Z axis.  (note that the order matters)
  1090.  
  1091. To work out the rotation directions, you must perform the famous "Computer
  1092. Graphics Aerobics" exercise.  Hold up your left hand.  point your thumb in the
  1093. positive direction of the axis you want to rotate about.  Your fingers will
  1094. curl in the positive direction of rotation.  This is the famous "left-hand
  1095. coordinate system".  If you want to use a right-hand system, as some CAD
  1096. systems do, the RIGHT vector in the VIEW_POINT needs to be changed.  See the
  1097. detailed description of the VIEW_POINT, and use your right hand for the
  1098. "Aerobics".
  1099.                        _
  1100.                      _| |_  _
  1101.                    _| | | |/ \
  1102.                   | | | | |  |
  1103.                   | | | | |  V
  1104.                   | | | | |   
  1105.                   | | | | |
  1106.                   |       \____
  1107.                   |         ___|
  1108.                   \        /
  1109.                    |      /
  1110.                    |     |
  1111.                    |     |
  1112.                    |     |
  1113.  
  1114.  
  1115. 6.1.3)  Colour
  1116.  
  1117. A colour consists of a red component, a green component, a blue component, and
  1118. possibly an alpha component.  All four components are floats in the range 0.0
  1119. to 1.0.  The syntax for Colours is the word "COLOUR" followed by any or all of
  1120. the RED, GREEN, BLUE or ALPHA components in any order.
  1121.  
  1122. For example:
  1123.  
  1124.      COLOUR  RED 1.0  GREEN 1.0  BLUE 1.0
  1125.      COLOUR  BLUE 0.56
  1126.      COLOUR  GREEN 0.45 RED 0.3 BLUE 0.1 ALPHA 0.3
  1127.  
  1128. Alpha is a transparency indicator.  If an object's colour contains some
  1129. transparency, then you can see through it.  If Alpha is 0.0, the object is
  1130. totally opaque.  If it is 1.0, it is totally transparent.
  1131.  
  1132. For those people who spell "Colour" the American way as "Color", the program
  1133. will also accept "COLOR" as equivalent to "COLOUR" in all instances.
  1134.  
  1135.  
  1136. 6.1.4)  Colour Maps
  1137.  
  1138. For wood, marble, spotted, agate, granite, and gradient texturing, the user
  1139. may specify arbitrary colours to use for the texture.  This is done by a
  1140. colour map or "colour spline".  When the object is being textured, a number
  1141. between 0.0 and 1.0 is generated which is then used to form the colour of the
  1142. point.  A Colour map specifies the mapping used to change these numbers into
  1143. colours.  The syntax is as follows:
  1144.  
  1145.      COLOUR_MAP
  1146.           [start_value end_value colour1 colour2]
  1147.           [start_value end_value colour1 colour2]
  1148.           ...
  1149.      END_COLOUR_MAP
  1150.  
  1151. The numeric value between 0.0 and 1.0 is located in the colour map and the
  1152. final colour is calculated by a linear interpolation (a smooth blending)
  1153. between the two colours in the located range.
  1154.  
  1155.  
  1156. 6.2)    The More Complex Data Types
  1157.  
  1158. 6.2.1)  Declare
  1159.  
  1160. The data types used to describe the objects in the world are a bit more
  1161. difficult to describe.  To make this task easier, the program allows users to
  1162. describe these types in two ways.  The first way is to define it from first
  1163. principles specifying all of the required parameters.  The second way allows
  1164. the user to define an object as a modification of another object (the other
  1165. object is usually defined from first principles but is much simpler).  Here's
  1166. how it works:
  1167.  
  1168. You can use the term DECLARE to declare a type of object with a certain
  1169. description.  The object is not included in the world but is made known to the
  1170. program that it can be used as a "prototype" for defining other objects by the
  1171. name given, as this basic example shows:
  1172.  
  1173.      DECLARE Sphere = QUADRIC   { First Principles definition of a sphere }
  1174.           <1.0 1.0 1.0>
  1175.           <0.0 0.0 0.0>
  1176.           <0.0 0.0 0.0>
  1177.           -1.0
  1178.      END_QUADRIC
  1179.  
  1180. To then reference the declaration elsewhere in your source file or in another
  1181. included one, and to actually include the object in the world, you would
  1182. define the object using the DECLARE'd object's name, like this:
  1183.  
  1184.      OBJECT
  1185.           QUADRIC Sphere
  1186.                SCALE <20.0 20.0 20.0>
  1187.           END_QUADRIC
  1188.           TEXTURE
  1189.              COLOUR White
  1190.              AMBIENT 0.2
  1191.              DIFFUSE 0.8
  1192.           END_TEXTURE
  1193.      END_OBJECT
  1194.  
  1195. The real power of declaration becomes apparent when you declare several
  1196. primitive types of objects and then define an object with several component
  1197. shapes, using either COMPOSITE methods or the CSG methods INTERSECTION, UNION,
  1198. or DIFFERENCE.  Also, using the DECLARE keyword to pre- define textures can
  1199. make several objects share a texture without the need for each object to store
  1200. a duplicate copy of the same texture, for more efficient memory usage.
  1201. Example:
  1202.  
  1203.      DECLARE Dull TEXTURE  { A Basic, Boring Texture }
  1204.           AMBIENT 0.3
  1205.           DIFFUSE 0.7
  1206.      END_TEXTURE
  1207.  
  1208.      OBJECT         { A Hot dog in a Hamburger Bun (?) }
  1209.           UNION
  1210.                QUADRIC Sphere
  1211.                     SCALE <20.0, 10.0, 20.0>
  1212.             TEXTURE Dull END_TEXTURE
  1213.                END_QUADRIC
  1214.                QUADRIC Cylinder_X
  1215.                     SCALE <40.0, 20.0, 20.0>
  1216.             TEXTURE Dull END_TEXTURE
  1217.                END_QUADRIC
  1218.           END_UNION
  1219.      END_OBJECT
  1220.  
  1221.  
  1222. Layered textures, new to version 2.10, may also be DECLARE'd.  The DECLARE
  1223. mechanism keeps looking for successive TEXTURE definitions and will layer them
  1224. onto the same texture until another DECLARE (or any other statement except
  1225. another TEXTURE) is encountered in the input data file.  For example:
  1226.  
  1227.  DECLARE Cloud_Wood TEXTURE  { This is the cloudy wood texture used earlier. }
  1228.    Dark_Wood
  1229.    TURBULENCE 0.0
  1230.    SCALE <0.2 0.2 0.2>
  1231.    PHONG 1.0
  1232.  END_TEXTURE
  1233.  TEXTURE        { This is layered onto the wood texture just defined. }
  1234.    TURBULENCE 0.5
  1235.    BOZO
  1236.    COLOUR_MAP
  1237.      { transparent to transparent }
  1238.      [0.0 0.6   COLOUR RED 1.0 GREEN 1.0 BLUE 1.0 ALPHA 1.0
  1239.      COLOUR RED 1.0 GREEN 1.0 BLUE 1.0 ALPHA 1.0]
  1240.  
  1241.      { transparent to white }
  1242.      [0.6 0.8   COLOUR RED 1.0 GREEN 1.0 BLUE 1.0 ALPHA 1.0
  1243.      COLOUR RED 1.0 GREEN 1.0 BLUE 1.0]
  1244.  
  1245.      { white to grey }
  1246.      [0.8 1.001 COLOUR RED 1.0 GREEN 1.0 BLUE 1.0
  1247.      COLOUR RED 0.8 GREEN 0.8 BLUE 0.8]
  1248.    END_COLOUR_MAP
  1249.    SCALE <0.4  0.08  0.4>
  1250.  END_TEXTURE
  1251.  
  1252. DECLARE (etc.) { Ends the definition of the layered "Cloud_Wood" texture. }
  1253.  
  1254. 6.2.2)  Viewpoint
  1255.  
  1256. The viewpoint tells the ray tracer the location and orientation of the camera.
  1257. The viewpoint is described by four vectors - Location, Direction, Up, and
  1258. Right.  Location determines where the camera is located.  Direction determines
  1259. the direction that the camera is pointed.  Up determines the "up" direction of
  1260. the camera.  Right determines the direction to the right of the camera.
  1261.  
  1262. A first principle's declaration of a viewpoint would look like this:
  1263.      
  1264.      VIEWPOINT
  1265.           LOCATION < 0.0  0.0  0.0>
  1266.           DIRECTION < 0.0  0.0  1.0>
  1267.           UP < 0.0  1.0  0.0 >
  1268.           RIGHT < 1.0  0.0  0.0>
  1269.      END_VIEWPOINT
  1270.  
  1271. This format becomes cumbersome, however, because the vectors must be hand
  1272. calculated.  This is especially difficult when the vectors are not lined up
  1273. with the X, Y, and Z axes as they are in the above example. To make it easier
  1274. to define the viewpoint, you can define one viewpoint, then modify the
  1275. description.  For example,
  1276.  
  1277.      VIEWPOINT
  1278.           LOCATION < 0.0  0.0  0.0>
  1279.           DIRECTION < 0.0  0.0  1.0>
  1280.           UP < 0.0  1.0  0.0 >
  1281.           RIGHT < 1.0  0.0  0.0 >
  1282.           TRANSLATE < 5.0  3.0  4.0 >
  1283.           ROTATE < 30.0  60.0  30.0 >
  1284.      END_VIEWPOINT
  1285.  
  1286. In this example, the viewpoint is created, then translated to another point in
  1287. space and rotated by 30 degrees about the X axis, 60 degrees about the Y axis,
  1288. and 30 degrees about the Z axis.
  1289.  
  1290. Unfortunately, even this is somewhat cumbersome.  So, in version 2.0 and
  1291. above, you can now specify two more parameters:
  1292.  
  1293.           SKY <vector>
  1294.           LOOK_AT <vector>
  1295.  
  1296. The SKY keyword tells the viewpoint where the sky is.  It tries to keep the
  1297. camera's UP direction aligned as closely as possible to the sky. The LOOK_AT
  1298. keyword tells the camera to look at a specific point.  The camera is rotated
  1299. as required to point directly at that point.  By changing the SKY vector, you
  1300. can twist the camera while still looking at the same point.
  1301.  
  1302. One subtle point:  the SKY direction is not necessarily the same as the UP
  1303. direction.  For example, consider the following situation:
  1304.  
  1305.           S^
  1306.            | /U
  1307.            |/
  1308.            C
  1309.             \
  1310.              \
  1311.               \
  1312.                O
  1313.  
  1314. If you said that the camera C has a SKY direction S and is looking at O, the
  1315. up direction will not point to the sky.  UP's like putting an antenna on your
  1316. camera.  If you point the camera downwards, the antenna will no longer point
  1317. straight up.
  1318.  
  1319. The RIGHT vector, as was mentioned previously, controls the aspect ratio of
  1320. the screen display.  It also determines the "handedness" of the coordinate
  1321. system in use.  A normal (left-handed) RIGHT statement would be:
  1322.  
  1323.     RIGHT < 1.3333 0.0 0.0 >
  1324.  
  1325. To use a right-handed coordinate system, as is popular in some CAD programs
  1326. and some other ray-tracers, such as Sculpt for the Amiga, use a RIGHT like:
  1327.  
  1328.     RIGHT < -1.3333 0.0 0.0 >
  1329.  
  1330. Some CAD systems also have the peculiar conception that the Z axis is the
  1331. "elevation" and is the "UP" direction instead of the Y axis.  If this is the
  1332. case you will want to change your "UP" statement to:
  1333.  
  1334.     UP < 0.0 0.0 1.0 >
  1335.  
  1336.  
  1337. Note that a pinhole camera model is used, so no focus or depth-of-field
  1338. effects are supported at this time.  For more detailed information on the
  1339. camera model, see the section "How it All Works."
  1340.  
  1341. 6.2.3)  Fog
  1342.  
  1343. Version 2.0 of the raytracer includes the ability to render fog.  To add fog
  1344. to a scene, place the following declaration outside of any object definitions:
  1345.  
  1346.      FOG
  1347.           COLOUR  {... the fog colour}
  1348.           200.0   {... the fog distance}
  1349.      END_FOG
  1350.  
  1351. The fog to colour ratio is calculated as 1-exp(-depth/distance), so at
  1352. depth 0, the colour is pure (1.0) with no fog (0.0).  At the fog distance,
  1353. you'll get 63% of the colour from the object's colour and 37% from the
  1354. fog colour.
  1355.  
  1356. 6.2.4)  Shapes
  1357.  
  1358. Shapes describe the shape of an object without mentioning any surface
  1359. characteristics like colour, surface lighting and reflectivity.
  1360.  
  1361. 6.2.4.1)    Quadric Shapes
  1362.  
  1363. The most general shape used by this system is called a Quadric Surface.
  1364. Quadric Surfaces can produce shapes like spheres, cones, cylinders,
  1365. paraboloids (dish shapes), and hyperboloids (saddle or hourglass shapes).
  1366.  
  1367. The easiest way to define these shapes is to include the standard file
  1368. "shapes.dat" into your program and to transform these shapes (using TRANSLATE,
  1369. ROTATE, and SCALE) into the ones you want.  To be complete, however, I will
  1370. describe the mathematical principles behind quadric surfaces.  Those who are
  1371. not interested in the mathematical details can skip to the next section. 
  1372.  
  1373. The quadric:
  1374.  
  1375.       QUADRIC
  1376.           <A B C>
  1377.           <D E F>
  1378.           <G H I>
  1379.           J
  1380.       END_QUADRIC
  1381.  
  1382. defines a surface in three dimensions which satisfies the following equation:
  1383.  
  1384.  
  1385.        A y**2  + B y**2  + C z**2
  1386.      + D xy    + E xz    + F yz
  1387.      + G x     + H y     + I z    + J = 0
  1388.  
  1389.  
  1390. (Did you really want to know that?  I didn't think so. :-)  DKB)
  1391.  
  1392. Different values of A,B,C,...J will give different shapes.  So, if you take
  1393. any three dimensional point and use its x, y, and z coordinates in the above
  1394. equation, the answer will be 0 if the point is on the surface of the object.
  1395. The answer will be negative if the point is inside the object and positive if
  1396. the point is outside the object.  Here are some examples:
  1397.  
  1398.      X**2 + Y**2 + Z**2 - 1 = 0     Sphere
  1399.      X**2 + Y**2 - 1 = 0            Cylinder along the Z axis
  1400.      X**2 + Y**2 - Z**2 = 0         Cone along the Z axis
  1401.  
  1402.  
  1403. 6.2.4.2)    Quadric surfaces the easy way
  1404.  
  1405. Now that doesn't sound so hard, does it?  Well, actually, it does.  Only the
  1406. hard-core graphics fanatic would define his objects using the QUADRIC
  1407. definition directly.  Even I don't do it that way and I know how it works
  1408. (Well, at least I worked it out once or twice :-) - DKB).
  1409.  
  1410. Fortunately, there is an easier way. The file "shapes.dat" already includes
  1411. the definitions of many quadric surfaces.  They are centered about the origin
  1412. < 0 0 0 > and have a radius of 1.  To use them, you can define shapes simply
  1413. as follows:
  1414.  
  1415.       INCLUDE "colors.dat"
  1416.       INCLUDE "shapes.dat"      { This is the important one for this example }
  1417.       INCLUDE "textures.dat"
  1418.  
  1419.      QUADRIC
  1420.           Cylinder_X
  1421.           SCALE < 50.0  50.0  50.0 >
  1422.           ROTATE < 30.0  10.0  45.0 >
  1423.           TRANSLATE < 2.0  5.0  6.0 >
  1424.      END_QUADRIC
  1425.  
  1426.  
  1427. You may have as many transformation lines (scale, rotate, and translate) as
  1428. you like in any order.  Usually, however, it's easiest to do a scale first,
  1429. one or more rotations, then finally a translation.  Otherwise, the results may
  1430. not be what you expect. (The transformations always transform the object about
  1431. the origin.  If you have a sphere at the origin and you translate it then
  1432. rotate it, the rotation will spin the sphere around the origin like planets
  1433. about the sun).
  1434.  
  1435.  
  1436.  
  1437. 6.2.4.3)    Spheres
  1438.  
  1439. Since spheres are so common in ray traced graphics, A SPHERE primitive has
  1440. been added to the system.  This primitive will render much more quickly than
  1441. the corresponding quadric shape.  The syntax is:
  1442.  
  1443.      SPHERE  <center> radius END_SPHERE
  1444.  
  1445. You can also add translations, rotations, and scaling to the sphere. For
  1446. example, the following two objects are identical:
  1447.  
  1448.      OBJECT
  1449.           SPHERE  < 0.0 25.0 0.0 > 10.0 END_SPHERE
  1450.           TEXTURE
  1451.              COLOR Blue
  1452.              AMBIENT 0.3
  1453.              DIFFUSE 0.7
  1454.           END_TEXTURE
  1455.      END_OBJECT
  1456.  
  1457.      OBJECT
  1458.           SPHERE  < 0.0 0.0 0.0 > 1.0
  1459.                TRANSLATE <0.0  25.0  0.0> 
  1460.                SCALE <10.0  10.0  10.0>
  1461.           END_SPHERE
  1462.           TEXTURE
  1463.              COLOR Blue
  1464.              AMBIENT 0.3
  1465.              DIFFUSE 0.7
  1466.           END_TEXTURE
  1467.      END_OBJECT
  1468.  
  1469. Note that Spheres may only be scaled uniformly. You cannot use:
  1470.  
  1471.      SCALE <10.0 5.0 2.0>
  1472.  
  1473. on a sphere.  If you need oblate (flattened) spheroids, use a scaled quadric
  1474. "Sphere" shape instead, as it can be arbitrarily scaled in any dimension.
  1475.  
  1476. 6.2.4.4)    Planes
  1477.  
  1478. Another primitive provided to speed up the raytracing is the PLANE. This is a
  1479. flat infinite plane.  To declare a PLANE, you specify the direction of the
  1480. surface normal to the plane (the UP direction) and the distance from the
  1481. origin of the plane to the world's origin. As with spheres, you can translate,
  1482. rotate, and scale planes.  Examples:
  1483.  
  1484.      PLANE <0.0  1.0  0.0> -10.0 END_PLANE   { A plane in the X-Z axes 10
  1485.                                              units below the world origin. }
  1486.  
  1487.      PLANE <0.0  1.0  0.0>  10.0 END_PLANE   { A plane in the X-Z axes 10
  1488.                                              units above the world origin. }
  1489.  
  1490.      PLANE <0.0  0.0  1.0>  -10.0 END_PLANE  { A plane in the X-Y axes 10
  1491.                                              units behind the world origin.}
  1492.  
  1493.  
  1494.  
  1495. 6.2.4.5)    Triangles
  1496.  
  1497. In order to make more complex objects than the class of quadrics will
  1498. permit, a new primitive shape for triangles has been added.  There are
  1499. two different types of triangles:  flat shaded triangles and smooth
  1500. shaded (Phong) triangles.
  1501.  
  1502. Flat shaded triangles are defined by listing the three vertices of the 
  1503. triangle.  For example:
  1504.    
  1505.      TRIANGLE  < 0.0   20.0  0.0>
  1506.                < 20.0  0.0   0.0>
  1507.                <-20.0  0.0   0.0>
  1508.      END_TRIANGLE
  1509.  
  1510. The smooth shaded triangles use Phong Normal Interpolation to calculate the
  1511. surface normal for the triangle.  This makes the triangle appear to be a
  1512. smooth curved surface.  In order to define a smooth triangle, however, you
  1513. must supply not only the vertices, but also the surface normals at those
  1514. vertices.  For example:
  1515.    
  1516.      SMOOTH_TRIANGLE
  1517.           {      points             surface normals     }
  1518.           <  0.0  30.0  0.0 >    <0.0   0.7071   -0.7071>
  1519.           < 40.0 -20.0  0.0 >    <0.0   -0.8664  -0.5   >
  1520.           <-50.0 -30.0  0.0 >    <0.0   -0.5     -0.8664>
  1521.      END_SMOOTH_TRIANGLE
  1522.  
  1523. As with the other shapes, triangles can be translated, rotated, and scaled.
  1524.  
  1525. NOTE 1:  Triangles cannot be used in CSG INTERSECTION or DIFFERENCE types
  1526. (described next) since triangles have no clear "inside".  The CSG UNION type
  1527. works acceptably, but with no real difference from a COMPOSITE made up of
  1528. TRIANGLE primitives.
  1529.  
  1530. NOTE 2:  To be honest, I don't expect mere mortals to work out the surface
  1531. normals of triangles.  Ideally, you'd have another program generate them for
  1532. you.  See the section on "Common Questions and Answers" for details on how
  1533. this might be done.
  1534.  
  1535.  
  1536. 6.2.4.6)    Quartic Surfaces
  1537.  
  1538. Quartic surfaces are 4th order surfaces, and can be used to describe a large
  1539. class of shapes including the torus, the lemniscate, etc.  The general
  1540. equation for a quartic equation in three variables is (hold onto your hat):
  1541.  
  1542.    a00 x^4     + a01 x^3 y   + a02 x^3 z   + a03 x^3     + a04 x^2 y^2 + 
  1543.    a05 x^2 y z + a06 x^2 y   + a07 x^2 z^2 + a08 x^2 z   + a09 x^2 + 
  1544.    a10 x y^3   + a11 x y^2 z + a12 x y^2   + a13 x y z^2 + a14 x y z + 
  1545.    a15 x y     + a16 x z^3   + a17 x z^2   + a18 x z     + a19 x +
  1546.    a20 y^4     + a21 y^3 z   + a22 y^3     + a23 y^2 z^2 + a24 y^2 z +
  1547.    a25 y^2     + a26 y z^3   + a27 y z^2   + a28 y z     + a29 y +
  1548.    a30 z^4     + a31 z^3     + a32 z^2     + a33 z       + a34
  1549.  
  1550. To declare a quartic surface requires that each of the coefficients 
  1551. (a0 -> a34) be placed in order into a single long vector of 35 terms.
  1552.  
  1553. As an example, the following object declaration is for a torus having major
  1554. radius 6.3 minor radius 3.5 (Making the maximum width just under 10).
  1555.  
  1556.      { Torus having major radius sqrt(40), minor radius sqrt(12) }
  1557.      OBJECT
  1558.       QUARTIC
  1559.       < 1.0   0.0   0.0    0.0     2.0   0.0   0.0   2.0   0.0 -104.0
  1560.         0.0   0.0   0.0    0.0     0.0   0.0   0.0   0.0   0.0    0.0
  1561.         1.0   0.0   0.0    2.0     0.0  56.0   0.0   0.0   0.0    0.0
  1562.         1.0   0.0 -104.0   0.0   784.0 >
  1563.       END_QUARTIC
  1564.       BOUNDED_BY
  1565.        SPHERE <0 0 0> 10 END_SPHERE
  1566.       END_BOUND
  1567.      END_OBJECT
  1568.  
  1569. The code to calculate Ray-Surface intersections for quartics is somewhat
  1570. slower than that for intersections with quadric surfaces.  Benchmarks on
  1571. a stock 8Mhz AT (with FPU) give results of around 1400 solutions per second
  1572. for 2nd order equations (quadrics) vs 444 per second for 3rd order equations
  1573. and 123 per second for 4th order equations (quartics).  So clever use of
  1574. bounding shapes can make a big difference in processing time.
  1575.  
  1576. While a great deal of time has gone into debugging the code for handling
  1577. quartic surfaces, I know for a fact that there are bad combinations of
  1578. surface equations and lighting orientations that cause math errors (crash).
  1579. If this happens to you, as the joke goes, "then don't DO that."
  1580.  
  1581. Here are some surfaces to get you started.
  1582.  
  1583. A Torus can be represented by the equation:
  1584.  
  1585.    x^4 + y^4 + z^4 + 2 x^2 y^2 + 2 x^2 z^2 + 2 y^2 z^2
  1586.    -2 (r0^2 + r1^2) x^2 + 2 (r0^2 - r1^2) y^2 - 2 (r0^2 - r1^2) z^2
  1587.    + (r0^2 - r1^2)^2 = 0
  1588.  
  1589. Where r0 is the "major" radius of the torus - the distance from the hole
  1590. of the donut to the middle of the ring of the donut, and r1 is the "minor"
  1591. radius of the torus - the distance from the middle of the ring of the donut
  1592. to the outer surface.  Described another way, a torus is a circle that is
  1593. revolved around an axis.  The major radius is the distance from the axis to
  1594. the center of the circle, the minor radius is the radius of the circle. (If
  1595. this were a Mac I could put a drawing in here to show you...)
  1596.  
  1597. Note that scaling surfaces like a torus scales everything. In order to change
  1598. the relationship between the size of the hole and the size of the ring, it is
  1599. necessary to enter new coefficients for the torus.
  1600.  
  1601. The only coefficients of the 35 that need to be filled in are:
  1602.  
  1603.     a0  = a20 = a30 = 1,
  1604.     a4  = a7  = a23 = 2,
  1605.     a9  = a32       = -2 (r0^2 + r1^2)
  1606.     a25             = 2 (r0^2 - r1^2)
  1607.     a34             = 2 (r0^2 - r1^2)^2
  1608.  
  1609. the torus can then be rotated and translated into position once its shape
  1610. has been defined. (See 'TORUS.DAT')
  1611.  
  1612. A generalization of the lemniscate of Gerono can be represented by the
  1613. equation:
  1614.  
  1615.    c^2 x^4 - a^2 c^2 x^2 + y^2 + z^2 = 0
  1616.  
  1617. where good start values are a = 1.0 and c = 1.0, giving the coefficients:
  1618.  
  1619.    a0 = a25 = a32 = 1,
  1620.    a9 = -1
  1621.  
  1622. (See the example file "LEMNISCA.DAT" for a more complete example)
  1623.  
  1624. A generalization of a piriform can be represented by the equation:
  1625.  
  1626.    -b c^2 x^4 - a c^2 x^3 + y^2 + z^2 = 0
  1627.  
  1628. where good start values are a = 4, b = -4, c = 1, giving the coefficients
  1629.  
  1630.    a0 = 4,
  1631.    a3 = -4,
  1632.    a25 = a32 = 1
  1633.  
  1634. (See the file "PIRIFORM.DAT" for more on this...)
  1635.  
  1636. There are really so many different QUARTIC shapes, we can't even begin to
  1637. list or describe them all.  If you are interested and mathematically inclied,
  1638. an excellent reference book for curves and surfaces where you'll find more
  1639. QUARTIC shape formulas is:
  1640.  
  1641.    "The CRC Handbook of Mathematical Curves and Surfaces"
  1642.    David von Seggern
  1643.    CRC Press
  1644.    1990
  1645.  
  1646.  
  1647. 6.2.4.7)    Constructive Solid Geometry (CSG)
  1648.  
  1649. This ray tracer supports Constructive Solid Geometry in order to make the
  1650. object definition abilities more powerful.  Constructive Solid Geometry allows
  1651. you to define shapes which are the union, intersection, or difference of other
  1652. shapes.  Unions superimpose the two shapes.  This has the same effect as
  1653. defining two separate objects, but is simpler to create and/or manipulate.
  1654. Intersections define the space where the two surfaces meet.  Differences allow
  1655. you to cut one object out of another.
  1656.  
  1657. CSG Intersections, Unions, and Differences can consist of two or more shapes.
  1658. They are defined as follows:
  1659.  
  1660.      OBJECT
  1661.           INTERSECTION
  1662.                QUADRIC
  1663.                     ...
  1664.                END_QUADRIC
  1665.  
  1666.                QUADRIC
  1667.                     ...
  1668.                END_QUADRIC
  1669.  
  1670.                QUADRIC
  1671.                     ...
  1672.                END_QUADRIC
  1673.           END_INTERSECTION
  1674.           ...
  1675.      END_OBJECT
  1676.  
  1677. UNION or DIFFERENCE may be used instead of INTERSECTION.  The order of the
  1678. shapes doesn't matter except for the DIFFERENCE shapes.  For CSG differences,
  1679. the first shape is visible and the remaining shapes are cut out of the first
  1680. (in reverse order from version 1.2 DIFFERENCE's).
  1681.  
  1682. Constructive solid geometry shapes may be translated, rotated, or scaled in
  1683. the same way as a Quadric surface.  The quadric surfaces making up the CSG
  1684. object may be individually translated, rotated, and scaled as well.
  1685.  
  1686. When using CSG, it is often useful to invert an shape so that it's inside-out.
  1687. The INVERSE keyword can be used to do this for any SPHERE, PLANE, or QUADRIC.
  1688. When INVERSE is used, the "inside" of the object is flipped to become the
  1689. "outside".  For Planes, "inside" is defined to be "in the opposite direction
  1690. to the "normal" or "up" direction.
  1691.  
  1692. Note that performing an INTERSECTION between an shape and some other INVERSE
  1693. shapes is the same as performing a DIFFERENCE.  In fact, the DIFFERENCE is
  1694. actually implemented in this way in the code.
  1695.  
  1696. 6.2.5)  Objects
  1697.  
  1698. There is more to defining an object than just its shape.  You must tell the
  1699. ray tracer about the properties of the object like surface colour, alpha,
  1700. reflectivity, refractivity, the index of refraction, and so on.  This may be
  1701. done by specifying it in the shape or the object.  Generally, an OBJECT
  1702. definition will contain two pieces of information about an object: First, what
  1703. shape it is, and second, what it's looks like (on the surface and throughout).
  1704. A typical object definition looks something like this:
  1705.  
  1706.      OBJECT
  1707.           QUADRIC Sphere
  1708.                TRANSLATE < 40.0 40.0 60.0 >
  1709.           END_QUADRIC
  1710.  
  1711.           TEXTURE
  1712.              AMBIENT  0.3
  1713.              DIFFUSE   0.7
  1714.              REFLECTION  0.3
  1715.              REFRACTION  0.3
  1716.              IOR 1.05
  1717.              COLOUR RED 1.0 GREEN 1.0 BLUE 1.0 ALPHA 0.5
  1718.           END_TEXTURE
  1719.      END_OBJECT
  1720.  
  1721. The following keywords may be used when defining objects:
  1722.  
  1723. 6.2.5.1)    COLOUR value
  1724.  
  1725. When used on an OBJECT (i.e., not inside a TEXTURE block), the COLOUR keyword
  1726. determines what colour to use for a low quality rendering when TEXTURE's are
  1727. ignored.  See the +q option for details on setting the low-quality option.
  1728.  
  1729. Example:
  1730.  
  1731.      COLOUR RED 1.0  BLUE 0.4
  1732.  
  1733.           - or -
  1734.  
  1735.      DECLARE Yellow = COLOUR RED 1.0 GREEN 1.0
  1736.           ...
  1737.      COLOUR Yellow
  1738.  
  1739.  
  1740. 6.2.5.2)    TRANSLATE vector
  1741. 6.2.5.3)    ROTATE vector
  1742. 6.2.5.4)    SCALE vector
  1743.  
  1744. Objects can be translated, rotated, and scaled just like surfaces.  If an
  1745. object is transformed, all textures attached to the object at that time are
  1746. transformed as well.  This means that if you have a TRANSLATE, ROTATE, or
  1747. SCALE before a TEXTURE, the texture will NOT be transformed.  If the SCALE
  1748. TRANSLATE, or ROTATE is after the TEXTURE, the texture will be transformed.
  1749.  
  1750. 6.2.5.5)    LIGHT_SOURCE
  1751.  
  1752. If the LIGHT_SOURCE keyword is used in the definition of an object, then the
  1753. object is included in the list of light sources.  It can light objects and
  1754. produce shadows.  (You should also specify the COLOUR of the light source, it
  1755. will usually be "White").  Light sources have a peculiar restriction:  The
  1756. light source MUST be TRANSLATED to its final position in the scene, so the
  1757. normal way to define a light source is a sphere or quadric centered about the
  1758. origin, then TRANSLATED to where desired in the final scene.  For example:
  1759.  
  1760.      OBJECT
  1761.           SPHERE <0.0  0.0  0.0> 2.0 END_SPHERE   {could be a quadric, too.}
  1762.           TRANSLATE <100.0  120.0  40.0>
  1763.  
  1764.           LIGHT_SOURCE
  1765.           COLOUR White      { This is the colour of the light emitted }
  1766.           TEXTURE
  1767.              COLOUR White   { This is the surface colour of the sphere }
  1768.              AMBIENT 1.0
  1769.              DIFFUSE 0.0
  1770.           END_TEXTURE
  1771.      END_OBJECT
  1772.  
  1773.  
  1774. NOTE: You MUST specify the colour of the light outside the TEXTURE block. This
  1775.       allows the renderer to quickly determine the colour of the light source
  1776.       without having to plow through the textures.  Any colour information
  1777.       inside the TEXTURE block is used to render the light source object itself
  1778.       if it is visible in the scene.  The subtle difference between the
  1779.       actual sphere object and the light ray emanation point (the center of
  1780.       the sphere) is why LIGHT_SOURCE's must be defined at (0,0,0) then
  1781.       TRANSLATE'd to where you want them.  It ties together and TRANSLATE's
  1782.       both the object itself and the light ray source point to the specified
  1783.       point in the scene.  Usually, light sources have an AMBIENT value of 1.0
  1784.       and a DIFFUSE of 0.0, but this is not a hard and fast rule.
  1785.  
  1786. 6.2.6)  TEXTURE
  1787.  
  1788. The texture feature is an experiment into functionally based modelling.  This
  1789. feature allows you to assign colouring schemes to objects.  Many procedural
  1790. surface textures are provided, and by using different colour maps with them,
  1791. nearly infinite permutations are possible.  For example, you can make some
  1792. object look like wood or marble, etc.  In DKBTrace, any parameter that changes
  1793. the appearance of the surface MUST be put into a TEXTURE block.
  1794.  
  1795. The basic TEXTURE syntax is as follows:
  1796.  
  1797.      TEXTURE
  1798.           0.05
  1799.           WOOD
  1800.           TURBULENCE 0.2
  1801.           TRANSLATE < 1.0 2.0 3.0 >
  1802.           ROTATE < 0.0 10.0 40.0 >
  1803.           SCALE < 10.0 10.0 10.0 >
  1804.      END_TEXTURE
  1805.  
  1806. Transformations are optional.  They allow you to transform the texture
  1807. independent of the object itself.  If you are doing animation, then the
  1808. transformations should be the same as the object transformations so that the
  1809. texture follows the object through 3-D space.
  1810.  
  1811. The floating-point value given immediately following the texture keyword is an
  1812. optional "texture randomness" value, which causes a minor random scattering of
  1813. calculated colour values and produces a sort of "dithered" appearance.  Note
  1814. this is BAD, BAD, BAD for animations!!  This is the ONLY "truly random" thing
  1815. in all of DKB, and will produce a most annoying flicker of flying pixels on
  1816. any textures animated with a "randomness" value used.
  1817.  
  1818. Instead of using WOOD, you may use MARBLE, BOZO, CHECKER, or a handful of
  1819. other interesting textures.  The WOOD and MARBLE textures are perturbed by a
  1820. turbulence function.  This makes them look more random and irregular than they
  1821. would normally appear.  The amount of turbulence can be changed by the
  1822. TURBULENCE keyword followed by a number.  Values from 0.1 to 0.3 seem to give
  1823. the best results.  The default is 0.0, or no turbulence. 
  1824.  
  1825. Note some of the textures given are coloration textures, such as MARBLE, WOOD
  1826. CHECKER, GRANITE, and AGATE.  These work with colour maps, and have default
  1827. "colour maps" they resort to if none are given.  The rest of the textures
  1828. available are "surface perturbation" textures, and do not directly affect the
  1829. colour of the object, but rather the surface's apparent orientation in space.
  1830. Examples of this are WAVES, RIPPLES, DENTS, BUMPS, and WRINKLES.  Note that
  1831. any given texture may include up to two actual textures, one coloration and
  1832. one surface perturbation choice per texture.  This would allow rippled wood,
  1833. or dented granite combinations, etc., but, keep in mind that any texture
  1834. transformations applied to one texture (i.e. TRANSLATE or SCALE) will also
  1835. transform the other one in the same fashion.
  1836.  
  1837.  
  1838. As of version 2.10, it is possible to create layered textures. If you use more
  1839. that one texture block, the raytracer will compute the colour of the last
  1840. texture and if there's any transparency in the colour (i.e., any alpha), it
  1841. will mix in some of the colour from the underlying textures.
  1842.  
  1843. IMPORTANT NOTE:  As of version 2.10, the keywords in this following section
  1844.                  CANNOT be used outside of a TEXTURE-END_TEXTURE structure.
  1845.                  This is a change in the input language from prior versions.
  1846.  
  1847. The following object surface lighting characteristics are available:
  1848.  
  1849. 6.2.6.1)    AMBIENT value
  1850.  
  1851. Ambient light is light that is scattered everywhere in the room.  An object
  1852. lit only by ambient light will appear to have the same brightness over the
  1853. entire surface.  The default value is very little ambient light (0.3).  The
  1854. value can range from 0.0 to 1.0. 
  1855.  
  1856. 6.2.6.2)    DIFFUSE value
  1857.  
  1858. Diffuse light is light coming from a light source that is scattered in all
  1859. directions.  An object lit only by diffuse light looks like a rubber ball with
  1860. a spot light shining on it.  The value can range from 0.0 to 1.0.  By default,
  1861. there is mostly diffuse lighting (0.7).
  1862.  
  1863. 6.2.6.3)    BRILLIANCE value
  1864.  
  1865. Objects can be made to appear more metallic by increasing their brilliance.
  1866. This controls the tightness of the basic diffuse illumination on objects and
  1867. minorly adjusts the appearance of surface shininess.  The default value is
  1868. 1.0.  Higher values from 3.0 to about 10.0 can give objects a somewhat more
  1869. shiny or metallic appearance.  This is best used in concert with either the
  1870. SPECULAR or PHONG highlighting.
  1871.  
  1872. 6.2.6.4)    REFLECTION value
  1873.  
  1874. By setting the reflection value to be non-zero, you can give the object a
  1875. mirrored finish.  It will reflect all other objects in the room.  The value
  1876. can range from 0.0 to 1.0.  By default there is no reflection. 
  1877.  
  1878. 6.2.6.5)    REFRACTION value
  1879.  
  1880. By setting the refraction value to be non-zero, the object is made transparent.
  1881. Light will be refracted through the object like a lens.  The value can be set
  1882. between 0.0 and 1.0.  There is no refraction by default. 
  1883.  
  1884. NOTE 1:  New for 2.10:  In order to refraction to work properly, you must have
  1885.          some ALPHA component in the surface colour.  In the places where the
  1886.          ALPHA is high, the refracted light can get through.  In places where
  1887.          the ALPHA is low, the refracted light is suppressed.  This is a
  1888.          change in the input language from prior versions.
  1889.  
  1890. NOTE 2:  The refracted light is filtered by (takes on) the surface colour.
  1891.  
  1892. NOTE 3:  In layered textures, the REFRACTION and IOR keywords MUST be in the
  1893.          last texture, otherwise they will not take effect.
  1894.  
  1895. NOTE 4:  If a texture has an ALPHA component and no value for REFRACTION was
  1896.          supplied, the renderer will simply transmit the ray through the
  1897.          surface with no bending.
  1898.  
  1899. 6.2.6.6)    IOR value
  1900.  
  1901. If the object is refracting light, then the IOR or Index of Refraction should
  1902. be set.  This determines how dense the object is.  A value of 1.0 will give no
  1903. refraction.  The Index of Refraction for air is 1.0, water is 1.33, glass is
  1904. 1.5, and diamond is 2.4. 
  1905.  
  1906. 6.2.6.7)    PHONG value
  1907.  
  1908. Controls the amount of Phong Specular Reflection highlighting on the object.
  1909. Causes bright shiny spots on the object, the colour of the light source that
  1910. is being reflected.  The size of the spot is defined by the value given for
  1911. PHONGSIZE below.  PHONG's value is typically from 0.0 to 1.0, where 1.0 causes
  1912. complete saturation of the object's colour to the light source's colour at the
  1913. brightest area (center) of the highlight.  There is no PHONG highlighting
  1914. given by default. 
  1915.  
  1916. 6.2.6.8)    PHONGSIZE value
  1917.  
  1918. Controls the size of the PHONG Highlight on the object, sort of an arbitrary
  1919. "glossiness" factor.  Values range from 1.0 (Very Dull) to 100 (Highly
  1920. Polished).  Default PHONGSIZE is 40 (plastic?) if not specified.  This is
  1921. simulating the fact that slightly reflective objects, especially metallic
  1922. ones, have microscopic facets, some of which are facing in the mirror
  1923. direction.  The more that are facing that way, the shinier the object appears,
  1924. and the tighter the specular highlights become.  Phong measures the average of
  1925. facets facing in the mirror direction from the light sources to the viewer. 
  1926.  
  1927. 6.2.6.9)    SPECULAR value
  1928.  
  1929. Very similar to PHONG Specular Highlighting, but a better model is used for
  1930. determining light ray/object intersection, so a more credible spreading of the
  1931. highlights occur near the object horizons, supposedly.  PHONG is thus included
  1932. for mostly academic reasons, but try them both and you decide which you like
  1933. better.  This effect is most obvious for light sources behind objects.  The
  1934. size of the spot is defined by the value given for ROUGHNESS below.  Like
  1935. PHONG, SPECULAR values are typically from 0.0 to 1.0 for full saturation.
  1936. Default is no SPECULAR highlighting.
  1937.  
  1938. Note that Specular and Phong highlights are NOT mutually exclusive.  It is
  1939. possible to specify both and they will both take effect.  Normally, however,
  1940. you will only specify one or the other.
  1941.  
  1942. 6.2.6.10)   ROUGHNESS value
  1943.  
  1944. Controls the size of the SPECULAR Highlight on the object, relative to the
  1945. object's "roughness".  Values range from 1.0 (Very Rough) to 0.001 (Very
  1946. Smooth).  The default value, if not specified, is 0.05 (Plastic?).  The
  1947. roughness or average directional distribution of the microfacets facing in the
  1948. same direction as the perpendicular surface "normal" cause the most notable
  1949. reflection of the highlight to the observer.
  1950.  
  1951.  
  1952. 6.2.6.11)   METALLIC
  1953.  
  1954. This keyword indicates that the colour of the specular and phong hightlights
  1955. will be the surface colour instead of the lightsource colour.  This creates
  1956. a metallic appearance.  When using this feature, you should set AMBIENT to
  1957. about 0.5 and set DIFFUSE to 0.0.
  1958.  
  1959.  
  1960. The following advanced procedural textures are available:
  1961.  
  1962. 6.2.6.12)   CHECKER - A colouring texture.
  1963.  
  1964. CHECKER texturing gives a checker-board appearance.  This option works best on
  1965. planes.  When using the CHECKER texturing, you must specify two colours
  1966. immediately following the word CHECKER.  These colours are the colours of
  1967. alternate squares in the checker pattern.  The default orientation of the
  1968. CHECKER texture is on an X-Z plane (good for ground work, etc.) but to use it
  1969. on an object which has mostly X-Y orientation (such as a sphere, for
  1970. instance), you must ROTATE the texture. 
  1971.  
  1972. To rotate the CHECKER texture onto an X-Y plane:
  1973.  
  1974.      TEXTURE
  1975.           CHECKER COLOUR White COLOUR Red
  1976.           SCALE <10.0 10.0 10.0>
  1977.           ROTATE <-90.0 0.0 0.0>   { Checkers now in the X-Y plane... }
  1978.      END_TEXTURE
  1979.  
  1980. 6.2.6.13)   CHECKER_TEXTURE - A colouring texture.
  1981.  
  1982. I've had many requests for a checker pattern to allow you to alternate between
  1983. wood and marble or any other two textures.  So, in version 2.10, I've added a
  1984. texture called CHECKER_TEXTURE that takes two textures instead of two colours.
  1985.  
  1986. In order to support layered textures, I've made the syntax a bit more verbose
  1987. than it would be otherwise.  The syntax is:
  1988.  
  1989.     TEXTURE
  1990.        CHECKER_TEXTURE
  1991.           TEXTURE ... put in a texture here ... END_TEXTURE
  1992.           TEXTURE ... add optional layers on top of that one ... END_TEXTURE
  1993.        TILE2
  1994.           TEXTURE ... this is the second tile texture END_TEXTURE
  1995.           TEXTURE ... a texture layered on top of the second tile END_TEXTURE
  1996.        END_CHECKER_TEXTURE
  1997.        AMBIENT ...
  1998.        DIFFUSE ...
  1999.    END_TEXTURE
  2000.  
  2001. Note that the textures in CHECKER_TEXTURE only use the surface colouring
  2002. texture information.  Information about AMBIENT, DIFFUSE, REFLECTION, etc.
  2003. and surface normal information (WAVES, RIPPLES) are ignored inside the
  2004. CHECKER_TEXTURE. (hey, what do you want for a 10 minute change?)
  2005.  
  2006.  
  2007. 6.2.6.14)   BOZO - A colouring texture.
  2008.  
  2009. BOZO texture basically takes a noise function and maps it onto the surface of
  2010. an object.  This "noise" is well-defined for every point in space.  If two
  2011. points are close together, they will have noise values that are close
  2012. together.  If they are far apart, their noise values will be fairly random
  2013. relative to each other. 
  2014.  
  2015. As mentioned above, for coloration textures such as WOOD, MARBLE, and BOZO,
  2016. etc., you may change the colouring scheme by using a colour map.  This map
  2017. allows you to convert numbers from 0.0 to 1.0 (which are generated by the ray
  2018. tracer) into ranges of colours. For example, the default BOZO colouring can be
  2019. specified by:
  2020.  
  2021.      TEXTURE
  2022.           BOZO
  2023.           COLOUR_MAP
  2024.                [0.0 0.4 COLOUR White COLOUR White]
  2025.                [0.4 0.6 COLOUR Green COLOUR Green]
  2026.                [0.6 0.8 COLOUR Blue COLOUR Blue]
  2027.                [0.8 1.0 COLOUR Red COLOUR Red]
  2028.           END_COLOUR_MAP
  2029.      END_TEXTURE
  2030.  
  2031. The easiest way to see how it works is to try it.  With a good choice of
  2032. colours it produces some of the most realistic looking cloudscapes you have
  2033. ever seen indoors!  Try a cloud color map such as:
  2034.  
  2035.      TEXTURE
  2036.           BOZO
  2037.           TURBULENCE 1.0      { A blustery day.  For a calmer one, try 0.2 }
  2038.           COLOUR_MAP
  2039.                [0.0 0.5  COLOUR RED 0.5 GREEN 0.5 BLUE 1.0  {blue to blue}
  2040.                     COLOUR RED 0.5 GREEN 0.5 BLUE 1.0]
  2041.                [0.5 0.6  COLOUR RED 0.5 GREEN 0.5 BLUE 1.0  {blue to white}
  2042.                     COLOUR RED 1.0 GREEN 1.0 BLUE 1.0]
  2043.                [0.6 1.001 COLOUR RED 1.0 GREEN 1.0 BLUE 1.0 {white to grey}
  2044.                     COLOUR RED 0.5 GREEN 0.5 BLUE 0.5]
  2045.           END_COLOUR_MAP
  2046.           SCALE <800.0 800.0 800.0>
  2047.           TRANSLATE <200.0 400.0 100.0>
  2048.      END_TEXTURE
  2049.  
  2050. The color map above indicates that for small values of texture, use a sky blue
  2051. color solidly until about halfway turbulent, then fade through to white on a
  2052. fairly narrow range.  As the white clouds get more turbulent and solid towards
  2053. the center, pull the color map toward grey to give them the appearance of
  2054. holding water vapor (like typical clouds). 
  2055.  
  2056. Check out sunset.dat for a really neat (but slow) sky pattern using ALPHA.
  2057.  
  2058.  
  2059. 6.2.6.15)   SPOTTED - A colouring texture.
  2060.  
  2061. Spotted texture is a sort of swirled random spotting of the colour of the
  2062. object.  If you've ever seen a metal organ pipe up close you know about what
  2063. it looks like (a galvanized garbage can is close...) Play with this one, it
  2064. might render a decent cloudscape during a very stormy day (?).  No extra
  2065. keywords are required.  Should work with colour maps.  With small scaling
  2066. values, looks like masonry or concrete.
  2067.  
  2068. 6.2.6.16)   AGATE - A colouring texture.
  2069.  
  2070. This texture is similar to Marble, but uses a different turbulence function.
  2071. The TURBULENCE keyword has no effect, and as such it is always very turbulent.
  2072.  
  2073. 6.2.6.17)   GRADIENT - A colouring texture.
  2074.  
  2075. This is a specialized texture that uses approximate local coordinates of an
  2076. object to control colour map gradients.  This texture ONLY works with colour
  2077. maps (one MUST be given!) and has a special <X, Y, Z> triple given after the
  2078. GRADIENT keyword, which specifies any (or all) axes to perform the gradient
  2079. action on.  Example: a Y gradient <0.0 1.0 0.0> will give an "altitude colour
  2080. map", along the Y axis.  Values given other than 0.0 are taken as 1.0.
  2081.  
  2082. For smooth repeating gradients, you should use a "circular" colour map, that
  2083. is, one in which the first colour value (0.0) is the same as the last one
  2084. (1.001) so that it "wraps around" and will cause smooth repeating gradient
  2085. patterns.  Scaling the texture is normally required to achieve the number of
  2086. repeating shade cycles you want.  Transformation of the texture is useful to
  2087. prevent a "mirroring" effect from either side of the central 0 axes.  Here is
  2088. an example of a gradient texture which uses a sharp "circular" color mapped
  2089. gradient rather than a smooth one, and uses both X and Y gradients to get a
  2090. diagonally-oriented gradient.  It produces a dandy candy cane texture! 
  2091.  
  2092.      TEXTURE
  2093.           GRADIENT < 1.0 1.0 0.0 >
  2094.           COLOUR_MAP
  2095.                [0.00 0.25  COLOUR RED 1.0 GREEN 0.0 BLUE 0.0
  2096.                     COLOUR RED 1.0 GREEN 0.0 BLUE 0.0]
  2097.                [0.25 0.75  COLOUR RED 1.0 GREEN 1.0 BLUE 1.0
  2098.                     COLOUR RED 1.0 GREEN 1.0 BLUE 1.0]
  2099.                [0.75 1.001 COLOUR RED 1.0 GREEN 0.0 BLUE 0.0
  2100.                     COLOUR RED 1.0 GREEN 0.0 BLUE 0.0]
  2101.           END_COLOUR_MAP
  2102.           SCALE <30.0 30.0 30.0>
  2103.           TRANSLATE <30.0 -30.0 0.0>
  2104.      END_TEXTURE
  2105.  
  2106. You may also specify a TURBULENCE value with the gradient to give a more
  2107. irregular colour gradient.  This may help to do neat things like fire or
  2108. corona effects.
  2109.  
  2110.  
  2111. 6.2.6.18)   GRANITE - A colouring texture.
  2112.  
  2113. This texture uses a simple 1/f fractal noise function to give a pretty darn
  2114. good grey granite texture.  Typically used with small scaling values (2.0 to
  2115. 5.0).  Also looks good with a little dithering (texture randomness).  Should
  2116. work with colour maps, so try your hand at pink granite or alabaster! 
  2117.  
  2118. 6.2.6.19)   RIPPLES - A surface perturbation texture.
  2119.  
  2120. As mentioned earlier, you may specify a surface perturbation texture which
  2121. can be used in conjunction with the above coloration textures.  RIPPLES makes
  2122. a surface look like ripples of water.  The RIPPLES option requires a value to
  2123. determine how deep the ripples are:
  2124.  
  2125.      TEXTURE
  2126.           WOOD
  2127.           RIPPLES 0.3
  2128.           TRANSLATE < 1.0 2.0 3.0 >
  2129.           ROTATE < 0.0 10.0 40.0 >
  2130.           SCALE < 10.0 10.0 10.0 >
  2131.      END_TEXTURE
  2132.  
  2133. (In this case, the WOOD, MARBLE, or BOZO, etc. keywords are optional).  If a
  2134. different colouring is specified (WOOD, MARBLE, or BOZO), then the COLOUR
  2135. parameter is ignored (except for light sources where it gives the light colour
  2136. or when rendering with a low -q option).
  2137.  
  2138.  
  2139. 6.2.6.20)   WAVES - A surface perturbation texture.
  2140.  
  2141. Another option that you may want to experiment with is called WAVES.  This
  2142. works in a similar way to RIPPLES except that it makes waves with different
  2143. frequencies.  The effect is to make waves that look more like deep ocean
  2144. waves. (I haven't done much testing on WAVES, so I can't guarantee that it
  2145. works very well). 
  2146.  
  2147. Both WAVES and RIPPLES respond to a texturing option called PHASE.  The PHASE
  2148. option allows you to create animations in which the water seems to move.  This
  2149. is done by making the PHASE increment slowly between frames.  The range from
  2150. 0.0 to 1.0 gives one complete cycle of a wave.
  2151.  
  2152. The WAVES and RIPPLES textures also respond to a keyword called FREQUENCY.  If
  2153. you increase the frequency of the waves, they get closer together.  If you
  2154. decrease it, they get farther apart.
  2155.  
  2156.  
  2157. 6.2.6.21)   BUMPS - A surface perturbation texture.
  2158.  
  2159. Approximately the same turbulence function as SPOTTED, but uses the derived
  2160. value to perturb the surface normal.  This gives the impression of a "bumpy"
  2161. surface, random and irregular, sort of like an orange.  After the BUMPS
  2162. keyword, supply a single floating point value for the amount of surface
  2163. perturbation.  Values typically range from 0.0 (No Bumps) to 1.0 (Extremely
  2164. Bumpy).  Values beyond 1.0 may do weird things.
  2165.  
  2166. 6.2.6.22)   DENTS - A surface perturbation texture.
  2167.  
  2168. Also a surface normal perturbing texture.  Interesting when used with metallic
  2169. textures, it gives impressions into the metal surface that look like dents.  A
  2170. single value is supplied after the DENTS keyword to indicate the amount of
  2171. denting required.  Values range from 0.0 (Showroom New) to 1.0 (Insurance
  2172. Wreck).  Use larger values at your own risk, they will raise your rates,
  2173. anyway... ;-) Scale the texture to make the pitting more or less frequent.
  2174.  
  2175. 6.2.6.23)   WRINKLES - A surface perturbation texture.
  2176.  
  2177. This is sort of a 3-D (normal perturbing) GRANITE.  It uses a similar 1/f
  2178. fractal noise function to perturb the surface normal in 3-D space.  With ALPHA
  2179. values of greater than 0.0, could look like wrinkled cellophane.  Requires a
  2180. single value after the WRINKLES keyword to indicate the amount of wrinkling
  2181. desired.  Values from 0.0 (No Wrinkles) to 1.0 (Very Wrinkled) are typical.
  2182.  
  2183. 6.2.6.24)   IMAGEMAP - A colouring texture.
  2184.  
  2185. This is a very special coloration texture that allows you to import a
  2186. bitmapped file in DUMP format (the format output by the ray-tracer), IFF
  2187. format or Compuserve GIF format and map that bitmap onto an object.  In the
  2188. texture of an object, you must give the IMAGEMAP keyword, the format, and a
  2189. file name.  The syntax is:
  2190.  
  2191.           IMAGEMAP [gradient] DUMP "filename" [ONCE]
  2192.      or   IMAGEMAP [gradient] IFF "filename" [ONCE]
  2193.      or   IMAGEMAP [gradient] GIF "filename" [ONCE]
  2194.  
  2195. The texture will then be mapped onto the object as a repeating pattern.  The
  2196. ONCE keyword places only one image onto the object instead of an infinitely
  2197. repeating tiled pattern.  When ONCE is used, the colour outside the mapped
  2198. texture is set to transparent.  You can use the layered textures to
  2199. place other textures or colours below the image.
  2200.  
  2201. In version 2.10 and up, you can specify the ALPHA values for the colour
  2202. registers of IFF or GIF pictures (at least for the modes that use colourmaps).
  2203. You can do this by putting the keyword ALPHA immediately following the
  2204. filename followed by the register value and transparency.  If the ALL keyword
  2205. is used instead of a register number, then all colours in that colourmap get
  2206. that alpha value.
  2207.  
  2208. Eg.
  2209.           IMAGEMAP <1.0 -1.0 0.0> IFF "mypic.iff"
  2210.              ALPHA ALL 0.0
  2211.  
  2212.    ...or     ALPHA 0   0.5
  2213.              ALPHA 1   1.0
  2214.              ALPHA 2   0.3
  2215.              ...
  2216.  
  2217.           ONCE
  2218.           ...
  2219.  
  2220.  
  2221. By default, the image is mapped onto the X-Y plane in the range (0.0, 0.0) to
  2222. (1.0, 1.0).  If you would like to change this default, you may use an optional
  2223. gradient <x, y, z> vector after the word IMAGEMAP.  This vector indicates
  2224. which axes are to be used as the u and v (local surface X-Y) axes.  The vector
  2225. should contain one positive number and one negative number to indicate the "u"
  2226. and "v" axes, respectively.  You may translate, rotate, and scale the texture
  2227. to map it onto the object's surface as desired.  Here is an example:
  2228.  
  2229.      INCLUDE "shapes.data"
  2230.  
  2231.      OBJECT
  2232.           QUADRIC Plane_XY END_QUADRIC
  2233.           TRANSLATE <0.0  -20.0  0.0>
  2234.  
  2235.           TEXTURE
  2236.                { make this texture use the x and z axes for the mapping. }
  2237.                IMAGEMAP <1.0  0.0  -1.0> GIF "image.gif"
  2238.                SCALE <40.0 40.0 40.0>
  2239.           END_TEXTURE
  2240.      END_OBJECT
  2241.  
  2242. Filenames specified in the IMAGEMAP statements will be searched for in the home
  2243. (current) directory first, and if not found, will then be searched for in
  2244. directories specified by any "-l" (library path) options active.  This would
  2245. facilitate keeping all your imagemaps (.dis, .gif or .iff) files in a
  2246. "textures" subdirectory, and giving an "-l" option on the command line to where
  2247. your library of imagemaps are. 
  2248.  
  2249. When I was bored with nothing to do, I decided that it would be neat to have
  2250. turbulent texture maps.  So, I said - "what the hell!"  You can specify
  2251. TURBULENCE with texture maps and it will perturb the image.  It may give some
  2252. bizarre results.  Is this useful?  I dunno.  It was easy to do so I did it.
  2253. Try it out and see what you get.
  2254.  
  2255.  
  2256. 6.2.7)  Composite Objects
  2257.  
  2258. Often it's useful to combine several objects together to act as a whole.  A
  2259. car, for example, consists of wheels, doors, a roof, etc.  A composite object
  2260. allows you to combine all of these pieces into one object.  This has two
  2261. advantages.  It makes it easier to move the object as a whole and it allows
  2262. you to speed up the ray tracing by defining bounding shapes that contain the
  2263. objects.  (Rays are first tested to see if they intersect the bounding shape.
  2264. If not, the entire composite object is ignored).  Composite objects are
  2265. defined as follows:
  2266.  
  2267.      COMPOSITE
  2268.           OBJECT
  2269.                ...
  2270.           END_OBJECT
  2271.  
  2272.           OBJECT
  2273.                ...
  2274.           END_OBJECT
  2275.           ...
  2276.  
  2277.           SCALE < 2.0 2.0 2.0 >
  2278.           ROTATE < 30.0 45.0 160.0 >
  2279.           TRANSLATE < 100.0 20.0 40.0 >
  2280.      END_COMPOSITE
  2281.  
  2282. Composite objects can contain other composite objects as well as regular
  2283. objects.  Composite objects cannot be light sources (although any number of
  2284. their components can).  This is because it is nearly impossible to determine
  2285. the true "center" of the composite object, and our light sources are pinpoint
  2286. ray sources from the center of the light source object, wherever that may be.
  2287.  
  2288.  
  2289. 6.3)    Bounding Shapes
  2290.  
  2291. Let's face it.  This program is no speed demon.  You can save yourself a lot
  2292. of time, however, if you use bounding shapes around any complex objects.
  2293. Bounding shapes tell the ray tracer that the object is totally enclosed by a
  2294. simple shape.  When tracing rays, the ray is first tested against the simple
  2295. bounding shape.  If it strikes the bounding shape, then the ray is further
  2296. tested against the more complicated object inside.
  2297.  
  2298. NOTE:  Don't use bounding shapes instead of CSG to clip objects.  You will not
  2299.        get the result you want.  For the raytracer to work properly, you must
  2300.        have the entire object inside the bounding shape.
  2301.  
  2302. To use bounding shapes, you simply include the following lines into the
  2303. declaration of your OBJECT or COMPOSITE_OBJECT:
  2304.  
  2305.      BOUNDED_BY
  2306.           a shape
  2307.      END_BOUND
  2308.  
  2309. An example of a Bounding Shape:
  2310.  
  2311.      OBJECT
  2312.           INTERSECTION
  2313.                SPHERE <0.0 0.0 0.0> 2.0 END_SPHERE
  2314.                PLANE <0.0 1.0 0.0> 0.0 END_PLANE
  2315.                PLANE <1.0 0.0 0.0> 0.0 END_PLANE
  2316.           END_INTERSECTION
  2317.  
  2318.           BOUNDED_BY
  2319.                SPHERE <0.0 0.0 0.0> 2.0 END_SPHERE
  2320.           END_BOUND
  2321.      END_OBJECT
  2322.  
  2323. The best bounding shape is a SPHERE since this shape is highly optimized.  Any
  2324. shape may be used, however, if more convenient.
  2325.  
  2326.  
  2327.  
  2328. 7)  Displaying the Images
  2329.  
  2330. When the ray tracer draws the picture on the screen, it doesn't make good
  2331. choices for the colour registers.  Without knowing all the needed colours
  2332. ahead of time, only approximate guesses can be made.  Usually, a post-
  2333. processor is really needed to view the final image correctly.
  2334.  
  2335. 7.1)    Amiga Systems
  2336.  
  2337. A post-processor has been provided for the Amiga which scans the picture and
  2338. chooses the best possible colour registers.  It then redisplays the picture.
  2339. For the Amiga, "DumpToIFF" can optionally save this picture in IFF format.
  2340. The syntax for the DumpToIFF post-processor is:
  2341.  
  2342.      DumpToIFF filename
  2343.  
  2344. where the filename is the one given in the -o parameter of the ray tracer.  If
  2345. you didn't specify the -o option, then use:
  2346.  
  2347.      DumpToIFF data.dis
  2348.  
  2349. If you want to save to an IFF file, then put the name of the IFF file after
  2350. the name of the data file:
  2351.  
  2352.      DumpToIFF data.dis picture
  2353.  
  2354. This will create a file called "picture" which contains the IFF image.
  2355.  
  2356.  
  2357. An alternative approach is to buy the commercial package called "The Art
  2358. Department" from ASDG.  You can then use the +fr option of the raytracer to
  2359. produce raw files which can be read in to TAD using Sculpt mode.  You can also
  2360. render using +fd to produce a dump format file, and use d2iff to convert this
  2361. to a 24-bit IFF image to load into TAD.
  2362.  
  2363.  
  2364. 7.2)    IBM Systems
  2365.  
  2366. For the IBM, you will probably want to use the +ft option (default if +f is
  2367. given) and write the image out in Targa-24 format.  If you have a Targa or
  2368. compatible display adapter, you may view the picture in the full 16 million
  2369. colors (that's why they still cost the big $$ bucks, but Hercules and Everex,
  2370. notably, are introducing their lower-priced SVGA-compatible 24-bit color display
  2371. systems for the IBM PC and compatibles).  If you don't have one of these, there
  2372. are several different post-processing programs available to convert the TARGA
  2373. true-color image into a more suitable color-mapped image (such as .GIF).  If
  2374. you have a VGA/MCGA or SVGA adapter capable of 320x200 by 256 colors or better,
  2375. then you may use the +d option which will display the image as it generates
  2376. using only approximate screen colors.  The +d option will Autodetect the type
  2377. of display adapter card you have and briefly say what kind it found before
  2378. displaying the picture.  If you say +dx where x is one of the predefined IBM
  2379. (S)VGA display adapter types, no hardware test is performed, so if you don't
  2380. have that type of (S)VGA card, -> DON'T <- use that particular +dx option!
  2381.  
  2382. When displaying the image to screen, a HSV conversion method is used (hue,
  2383. saturation, value).  This is a convenient way of translating colors from a
  2384. "true color" format (16 million) down a "colour mapped" format of something
  2385. reasonable (like 256), while still approximating the color as closely as the
  2386. available display hardware permits.  As mentioned previously, the tracer has
  2387. no way of knowing which colors will be finally used in the image, nor can it
  2388. deal properly with all of the colors which will be generated (up to 16M), so
  2389. only 4 shades each of 64 possible hues are mapped into the palette DAC, as
  2390. well as black, white, and two grey levels. The advantage a post-processor has
  2391. in choosing mapped colors is that it can throw away all the unused colors in
  2392. the palette map, and thereby free up some space for making better gradient
  2393. shades of the colors that are actually used.
  2394.  
  2395. There are several available image processing programs that can do this, a
  2396. public domain one that is very good is PICLAB, by the Stone Soup Group (the
  2397. folks who brought you FRACTINT).  The procedure is to load the TARGA file,
  2398. then use the MAKEPAL command to generate a 256 color map which is the
  2399. histogram-weighted average of the most-used colors in the image (You could
  2400. also PLOAD a palette file from FRACTINT or one you previously had saved using
  2401. PSAVE).  You then MAP the palette onto the image one of two ways:
  2402.  
  2403.      1)   If the DITHER variable is OFF, a nearest-match-color-fit is used,
  2404.           which can sometimes produce unwanted "banding" of colored regions
  2405.           (called false contours).
  2406.      2)   If the DITHER variable is ON, then a standard dither is used to
  2407.           determine final color values.  This is much better at blending the
  2408.           color bands, but can produce noise in reflections and make mirrors
  2409.           appear dirty or imperfect.
  2410.  
  2411. Then you would typically SHOW the image or GSAVE it into GIF format.  While
  2412. the picture is still in the unmapped form (TARGA, etc.) you can perform a
  2413. variety of advanced image processing transformations and conversions, so save
  2414. the .TGA or .RAW files you make (in case you ever get a TARGA card, or give
  2415. them to a friend who has one!).
  2416.  
  2417. A commercial product that also does a good job of nearest-match-color-fit is
  2418. the CONVERT utility of The AutoDesk Animator.  However, the dither effect is
  2419. not as good as that of PICLAB.  To convert the file in AA's CONVERT, you LOAD
  2420. TARGA, then in the CONVERT menu, go to the SCALE function and just hit RENDER.
  2421. Click on the DITHER (lights up with an asterisk when on) if you want it to use
  2422. it's dithering.  CONVERT will scale (if asked to) and then do a histogram of
  2423. total used colors like PICLAB, but then makes 7 passes on the color map and
  2424. image to determine shading thresholds of each hue.  This nearly eliminates the
  2425. color banding (false contours) in a lot of cases without resorting to good 'ol
  2426. dithering.  By now you must get the feeling DITHER is a 4-letter word.  If
  2427. you have a low-resolution display, it is.  If you have too few colors,
  2428. however, it can be a saving grace.  At resolutions of 640x400 or higher the
  2429. "spray paint" effect of dithering and anti-aliasing is much less noticeable,
  2430. and effects a much smoother blending appearance.
  2431.  
  2432. A new package to show up in the public domain/shareware circles for the IBM
  2433. is something called Image Alchemy, by Handmade Software.  It will convert
  2434. TARGA format to GIF files and do a decent job of palette selection and
  2435. dithering.  To use it simply say "ALCHEMY file.tga file.gif -g -8 -c256".
  2436. It also features a quick-and-dirty display mode where it uses a standardized
  2437. palette in much the same way DKB's +d option does, but offers dithering of the
  2438. image while using the pre-defined palette, for a somewhat better quick display.
  2439.  
  2440.  
  2441. 7.3)    Unix Systems
  2442.  
  2443. I don't have many details on Unix systems, but I hear that the FBM utilities
  2444. work well to convert the Dump format files into various formats of images.
  2445. For people with access to anonymous FTP over USENET, the FBM utilities are
  2446. available from nl.cs.emu.edu (128.2.222.56) in directory /usr/mlm/ftp.
  2447.  
  2448.  
  2449.  
  2450. 8)  DKBTrace Utilities
  2451.  
  2452. In many cases, creating data files for DKBTrace is difficult and tedious.  To
  2453. help remedy this problem, I and various other people have developed some
  2454. utilities to create data files.  These utilities are described below.
  2455.  
  2456. As well, there are some utilities that perform operations on the image files
  2457. created by DKBTrace.  These utilities convert between various formats and
  2458. allow you to modify or merge output files together.
  2459.  
  2460. I'd like to thank all the people who wrote these utilities and sent them to
  2461. me.  If anybody else comes up with other utilities, please let me know and
  2462. I'll include them in the distribution.
  2463.  
  2464. Some of these utilities are written in BASIC in IBM systems.  As such, they
  2465. are not easily portable from system to system.  If anyone wants to convert
  2466. them to C, let me know and I'll post the C versions.
  2467.  
  2468. 8.1)    Data File Creation Utilities
  2469.  
  2470. The data creation utilities fall into two categories:  Those that convert from
  2471. some other format into DKB format, and those that generate DKB files using
  2472. algorithmic techniques.  These utilities are described below.
  2473.  
  2474. 8.1.1)  SA2DKB
  2475.  
  2476. This program converts Sculpt-Animate 3D & 4D data files into DKB format.  It
  2477. currently only supports the basic triangles and textures. It doesn't support
  2478. smooth triangles (it treats them like normal triangles), light sources,
  2479. cameras, or floors. 
  2480.  
  2481. (This utility was formerly called "Sculpt2DKB" but the IBM systems out there
  2482. kept calling it "SCULPT2D", then couldn't figure out what a 2D program had to
  2483. do with raytracing or what the nonexistent Amiga program called "Sculpt-2D"
  2484. was :-)
  2485.  
  2486. 8.1.2)  DXF2DKB
  2487.  
  2488. This utility converts AutoCAD DXF (Drawing eXchange Format) files into
  2489. DKBTrace format scene description files.  It was written by Aaron Collins.  It
  2490. does not support all of the DXF primitives, but will suffice for simple
  2491. objects and scenes after EXPLODE'ing and DXFOUT'ing then in AutoCAD.
  2492.  
  2493. 8.1.3)  ShellGen
  2494.  
  2495. ShellGen is a BASIC program written by Dan Farmer.  It's based on a short code
  2496. fragment from Clifford Pickover's book "Computers, Pattern, Chaos, and Beauty"
  2497. (St. Martin's Press).  This code fragment was reprinted in Ray Tracing News
  2498. Issue 3.3.
  2499.  
  2500. As far as I know, the BASIC program only works on IBM's.  It does, however,
  2501. allow you to change the parameters and see a quick outline of what the result
  2502. will look like.
  2503.  
  2504. For those people without IBM's, I've changed the original code fragment to at
  2505. least output a DKB-format file.  No user interface has been provided, however.
  2506.  
  2507. 8.1.4)  Twister
  2508.  
  2509. Twister is a C program written by Drew Wells (CIS 73767,1244).  It creates
  2510. data files for twisted shapes.  The program uses a text interface and prompts
  2511. the user with a question/answer format.
  2512.  
  2513. 8.1.5)  Chem2DKB
  2514.  
  2515. Chem2DKB is an IBM BASIC program written by Dan Farmer.  It takes models
  2516. generated by the CHEM.EXE program written by Larry Puhl.
  2517.  
  2518. 8.1.6)  Lissajou
  2519.  
  2520. This is an IBM BASIC program written by Dan Farmer.  It creates data files for
  2521. lissajous figures.  The basic algorithms were from Clifford Pickover.  See
  2522. Scientific American Jan. '91 and Omni Feb '90 for examples.
  2523.  
  2524.  
  2525. 8.2)    Output File Manipulation Utilities
  2526.  
  2527. These utilities perform some useful manipulations on the dump format and Targa
  2528. format output files from DKBTrace.  I'd like to thank the people who wrote
  2529. these utilities and provided them for general distribution.
  2530.  
  2531. 8.2.1)  dump2i24   (DumpToIFF24)
  2532.  
  2533. This program was written by Helge E. Rasmussen (her@compel.dk).  It converts
  2534. the dump format files produced by DKBTrace into 24-bit IFF format files.
  2535. These files can then be read by a variety of programs including "The Art
  2536. Department" by ASDG.
  2537.  
  2538. 8.2.2)  catdump
  2539.  
  2540. This utility was written by Ville Saari vsaari@niksula.hut.fi (and copyright
  2541. by the Ferry Island Pixelboys.)  It takes two or more partially rendered files
  2542. in DKBTrace's dump format and merges them into one file.  This is useful for
  2543. all sorts of things like rendering different parts on different computers and
  2544. combining the results. 
  2545.  
  2546. NOTE:  Be careful if you combine pictures produced on different systems.  If
  2547. the random number generator works differently between the two systems, the
  2548. textures may look completely different from one another.  So long as you
  2549. use the same executable, you should be fine.
  2550.  
  2551. 8.2.3)  combdump  (combine dump)
  2552.  
  2553. This utility was also written by Ville Saari.  It takes two images generated
  2554. with DKBTrace with slightly different viewpoints, and creates one dump-format
  2555. image file to be viewed with RED-BLUE or RED-GREEN 3D glasses.  The program
  2556. allows you to compensate for the exact filtering characteristics of your
  2557. glasses to get the best possible result.
  2558.  
  2559. 8.2.4)  dump2mtv
  2560.  
  2561. This is yet another utility written by Ville Saari.  This one converts
  2562. DKBTrace dump format files onto MTV format used by the MTV and RayShade
  2563. raytracers.
  2564.  
  2565. 8.2.5)  dump2raw
  2566.  
  2567. The dump2raw utility was written by Aaron Collins to convert the dump format
  2568. output of DKBTrace into three separate files for red, green, and blue.  On the
  2569. IBM, the extensions for these files are "r8", "g8", and "b8".  On the other
  2570. systems, they are "red", "grn" and "blu".
  2571.  
  2572. Version 2.10 of the raytrace allows you to use the +fr option to output raw
  2573. format files directly without the need for a conversion program like this.
  2574.  
  2575. 8.2.6)  halftga
  2576.  
  2577. The halftga utility (written by Aaron Collins) shrinks a Targa-format file to
  2578. exactly half its original size.  This file can then be converted into a GIF
  2579. image and used in an IMAGE_MAP statement.  For systems with little memory
  2580. available for imagemaps, this command can be a life-saver. 
  2581.  
  2582. 8.2.7)  gluetga
  2583.  
  2584. This utility (by Aaron Collins) is similar to catdump but works for Targa
  2585. format files.  It takes several partially-rendered Targa files and glues them
  2586. together into one image. 
  2587.  
  2588. 8.2.8)  tga2dump
  2589.  
  2590. This utility was written by Aaron Collins.  It converts Targa format 16, 24,
  2591. and 32 bit images into DKB's dump format for use in image-mapping.
  2592.  
  2593.  
  2594. 8.3)    Animation Utilities
  2595.  
  2596. One of the most frequent questions I'm asked is whether or not DKBTrace
  2597. supports animation.  The answer is no, not directly.  However, I have made
  2598. some changes to the program to provide frame-to-frame consistency so you can
  2599. use it for animation if you want to.  The problem, then, is creating the data
  2600. files for each individual frame.  That's what this section is all about.
  2601.  
  2602. 8.3.1)  RayScene
  2603.  
  2604. Although RayScene is not being distributed with this raytracer, I thought I'd
  2605. at least mention it and tell you where you can get it.  RayScene is a program
  2606. that creates data files for DKBTrace based on a high-level (higher-level?)
  2607. description of the motion of the camera and the objects.  It was written by
  2608. Jari K{hk|nen (hole@tolsun.oulu.fi) and Panu Hassi (oldfox@tolsun.oulu.fi) and
  2609. is available by anonymous FTP from tolsun.oulu.fi (128.214.5.6) in the
  2610. directory /pub/rayscene or from iear.arts.rpi.edu in the directory
  2611. /pub/graphics/ray/rayscene.
  2612.  
  2613.  
  2614. This explanation of RayScene was sent to me by Panu Hassi;
  2615.  
  2616.    "I've tried animation with DBW before DKBTrace2.0 was released.  
  2617.     The procedure was this: First I wrote the first scene file, copied it 
  2618.     for NUMBER_OF_FRAMES times and then edited some parts of those files 
  2619.     to create movement etc.  If something went wrong (I accidentally edited 
  2620.     wrong value etc), I had to edit all those scene files again to make the
  2621.     changes.  Not so nice if there are 100 files to edit...
  2622.     
  2623.     So a friend of mine, Jari K{hk|nen, and I decided to write RayScene to
  2624.     make that process even a little easier.  With RayScene the process
  2625.     goes like this:  you create a scene file and mark the places that 
  2626.     should be changed with a variable, like:
  2627.  
  2628.     BOUNDED_BY                              
  2629.          SPHERE <0.0 0.0 0.0> #sphere_size# END_SPHERE
  2630.     END_BOUND
  2631.     
  2632.     Then you create another file where the values for these variables are
  2633.     listed.  Rayscene simply creates N scene files inserting current value of
  2634.     each variable to proper place.  That's all :D
  2635.     
  2636.     We have included couple of simple utilities that help with creating
  2637.     those variable values, but the original scene files are still created
  2638.     'manually'.  Still, the results have been really nice.  There are 
  2639.     several animations for Amiga and PC in tolsun.oulu.fi."
  2640.  
  2641. 9)  How it All Works (or How to Get What You Want)
  2642.  
  2643. The information in this section is designed for people who are reasonably
  2644. familiar with the raytracer and want more information on how things work so
  2645. they can push it to its limits.  You probably don't need this level of detail
  2646. to make interesting data files, but if you suddenly get confused about
  2647. something the program did, this section may help you figure it out.
  2648.  
  2649. 9.1)    Viewpoints
  2650.  
  2651. Viewpoints can be completely defined by four vectors.  The LOCATION is easy.
  2652. That's where the camera is.  The DIRECTION is a vector that starts at the
  2653. LOCATION and points to the center of a window.  The UP vector starts at the
  2654. center of the window and points to the center of the top edge.  The RIGHT
  2655. vector starts at the center of the window and points to the center of the
  2656. right edge. 
  2657.  
  2658.                               |\
  2659.                               | \
  2660.                               |  \
  2661.                               |   \
  2662.                               |  ^ \
  2663.                               |  |Up|
  2664.                               |  |  |
  2665.                               |  |  |
  2666.     Location *------------------->  |
  2667.                 Direction     |   \ |Right
  2668.                               |    \|
  2669.                               \     |
  2670.                                \    |
  2671.                                 \   |
  2672.                                  \  |
  2673.                                   \ |
  2674.                                    \|
  2675.  
  2676. The window is then divided up according to the resolution you specified and
  2677. rays are fired through the pixels out into the world.  For an eye ray,
  2678. therefore, the equation of the ray is:
  2679.  
  2680.    Location + t (Direction + ((height - y)*UP) + (x*RIGHT))
  2681.  
  2682. where "t" is a parameter that determines the distance from the eye to the
  2683. object being tested.  The Y coordinate is inverted by subtracting it from
  2684. height because most graphics systems put 0,0 in the top left corner of the
  2685. screen.
  2686.  
  2687. This viewpoint model is very flexible.  It allows you to use left-handed or
  2688. right-handed coordinate systems.  It also doesn't require that the DIRECTION,
  2689. UP, and RIGHT vectors be mutually orthogonal.  If you want, you can distort
  2690. the camera to get really bizarre results.
  2691.  
  2692. Once the basic four vectors are specified, it's possible to use the SKY and
  2693. LOOK_AT vectors to point the camera.  You must specify the SKY vector first,
  2694. but let me describe the LOOK_AT vector first.  LOOK_AT tells the camera to
  2695. rotate in such a way that the LOOK_AT point appears in the center of the
  2696. screen.  To do this, the camera first turns in the left-to-right direction
  2697. (longitude in Earth coordinates) until it's lined up with the LOOK_AT point.
  2698. It then turns in the up/down direction (latitude in Earth coordinates) until
  2699. it's looking at the desired point.
  2700.  
  2701. Ok, now we're looking at the proper point.  What else do we have to specify?
  2702. If you're looking at a point, you can still turn your camera sideways and
  2703. still be looking at the same spot.  This it the orientation that the SKY
  2704. direction determines.  The camera will try to position itself so that the
  2705. camera's UP direction lines up as closely as possible to the SKY direction.
  2706.  
  2707. Put another way - in airplane terms, the LOOK_AT vector determines your
  2708. heading (north, south, east, or west), and your pitch (climbing or
  2709. descending).  The SKY vector determines your banking angle.
  2710.  
  2711. 9.2)    Ray-Object Intersections
  2712.  
  2713. For every pixel on the screen, the raytracer fires at least one ray through
  2714. that pixel into the world to see what it hits.  For each hit (well, almost),
  2715. it calculates rays to each of the light sources to see if that point is
  2716. shadowed from that light source.  For reflecting objects, a reflected ray is
  2717. traced.  For refracting objects, a refracting ray is traced.  That all adds up
  2718. to a lot of rays.
  2719.  
  2720. Every ray is tested against every object in the world to see if the ray hits
  2721. that object. This is what slows down the raytracer.  You can make things
  2722. easier by using simple bounding shapes on your objects.
  2723.  
  2724. Fortunately, all ray-object intersections for all shapes in DKBTrace can be
  2725. solved by a simple quadratic equation.  This is why QUADRICs are used in
  2726. DKBTrace.  Solving for things like B-Splines, Bezier Splines, NURBS, Torus',
  2727. etc. is a lot more complicated.  That's why I haven't implemented primitives
  2728. for these shapes.
  2729.  
  2730. 9.3)    Transparency and Refraction
  2731.  
  2732. This section get really complicated because of the way transparency and
  2733. refraction are implemented.  If you don't really care, skip to the next
  2734. section. If you don't mind slogging through this and getting confused, then
  2735. read on.
  2736.  
  2737. - you've been warned -
  2738.  
  2739. The way that transparency and refraction work has changed slightly from
  2740. previous versions.  Now, transparency and refraction work together instead of
  2741. separately.
  2742.  
  2743. First, let me distinguish between reflected light and filtered light.  Suppose
  2744. you painted a table with patches of colour.  You then took some red sand and
  2745. sprinkled it on top of the various colours.  The red sand will tint the
  2746. colours red, but you will still see some of the original colour.  If, instead,
  2747. you took a sheet of red plexiglass and put it on top of the table, all you
  2748. could see would be shades of red.  That's because the plexiglass filter ONLY
  2749. allows the red colour to show through.
  2750.  
  2751. In DKBTrace, the layered textures work like the red sand - the colours on top
  2752. mix with the underlying colours depending on the density (ALPHA) of the
  2753. distribution.
  2754.  
  2755. Refraction, however, works like a filter.  The surface colour determines that
  2756. colours of light are allowed to pass from the inside of the object to the
  2757. outside, and vice versa.  Here are some filter colours:
  2758.  
  2759.    RED 1.0  GREEN 0.0  BLUE 0.0   ALPHA 1.0    - a red filter
  2760.    RED 1.0  GREEN 1.0  BLUE 1.0   ALPHA 1.0    - clear glass
  2761.    RED 0.0  GREEN 0.0  BLUE 0.0   ALPHA 1.0    - a dark filter - this will
  2762.                                                  appear black.
  2763.  
  2764. Now, consider the following layered textures:
  2765.  
  2766.    TEXTURE COLOUR Green ALPHA 0.6 END_TEXTURE
  2767.    TEXTURE COLOUR Yellow ALPHA 0.3 REFRACTION 0.5 END_TEXTURE
  2768.  
  2769. (Keep in mind that the last texture is on top.)
  2770.  
  2771. NOTE: In layered textures, only the REFRACTION component of the LAST entry has
  2772. any effect.
  2773.  
  2774. The colour you get is calculated like this:
  2775.  
  2776.          ____  Full Brightness
  2777.          |
  2778.          |
  2779.          |
  2780.          |
  2781.          |
  2782.          |   7/10 of pixel's colour is Yellow
  2783.          |
  2784.          |
  2785.          |
  2786.          |
  2787.          |
  2788.          |---
  2789.          |    
  2790.       -  |   3/10 (alpha) left over for underlying colour
  2791.      |   |
  2792.      |   |
  2793.      |   ----  Full Darkness
  2794.      |
  2795.      |
  2796.      |
  2797.      |
  2798.      |   ____  From the 3/10 available:
  2799.      |   |
  2800.      |   |
  2801.      |-> |   4/10 is green
  2802.          |
  2803.          |
  2804.          |---6/10 (alpha) is available for refraction
  2805.          |
  2806.          |
  2807.          |
  2808.          |
  2809.          |-- 5/10 of that (6/10) is passed through from refraction
  2810.          |        and filtered by the combined filter colour
  2811.          |        (yellow filtered by green).
  2812.          |
  2813.          |
  2814.          |
  2815.          ----
  2816.  
  2817.  
  2818.  
  2819. So, the top texture layer supplies some fraction of the light that reflects off
  2820. the surface of the object.  If the ALPHA was non-zero, it allows the lower 
  2821. textures to supply the remainder.  If, after all the textures are processed,
  2822. there's still some fraction left over, it is applied to the light that's
  2823. refracted through the object.
  2824.  
  2825. This algorithm probably doesn't coincide with reality, but neither does the rest
  2826. of the raytracer, so I'm not terribly concerned about it.
  2827.  
  2828. 9.4)    Textures, Noise, and Turbulence
  2829.  
  2830. If there's one thing that DKBTrace is known for, it's textures.  Here's how
  2831. they really work.  If you want some good reading material, check out "An Image
  2832. Synthesizer" by Ken Perlin in the SIGGRAPH '84 Conference Proceedings.
  2833.  
  2834. Let's start with a marble texture.  Real marble is created when different
  2835. colours of sediments are laid down one on top of another and compressed to
  2836. form solid rock.
  2837.  
  2838. For example, take a simple block of marble:
  2839.           ___________
  2840.          /          /|
  2841.         /          / |
  2842.        /__________/  |
  2843.        |   Red    | /|
  2844.        |----------|/ |
  2845.        |  White   | /|
  2846.        |----------|/ |
  2847.        |   Red    | /|
  2848.        |----------|/ |
  2849.        |  White   | /
  2850.        |__________|/
  2851.  
  2852. If you carve a shape put of this block of marble, you will get red and white
  2853. bands across it.
  2854.  
  2855. Now, consider wood.  The rings in wood are created when the tree grows a new
  2856. outer shell every year.  Hence, we have concentric cylinders of colours:
  2857.  
  2858.                 ______
  2859.                /      /
  2860.               /      / \
  2861.              /      /   \
  2862.             /      /     \
  2863.            /      /      |
  2864.           /______/       |
  2865.          / _____ \       |
  2866.         / / ___ \ \      |
  2867.        / / / _ \ \ \     /    (how do you draw a log in ASCII??!!)
  2868.       / / / / \ \ \ \   /
  2869.       | | | | | | | |  /
  2870.       | | | |O| | | | /
  2871.       | | | | | | | |/
  2872.       \ \ \ \_/ / / /
  2873.        \ \ \___/ / /
  2874.         \ \_____/ /
  2875.          \_______/
  2876.  
  2877. Cutting a shape out of a piece of wood will tend to give you rings of colour.
  2878.  
  2879. Now, this is fine, but the textures are still a bit boring.  For the next
  2880. step, we blend the colours together to create a nice smooth transition.  This
  2881. makes the texture look a bit better.  The problem, though, is that it's too
  2882. regular - real marble and wood aren't so perfect.
  2883.  
  2884. Before we make our wood and marble look any better, let's look at how we make
  2885. noise.  Noise (in raytracing) is sort of like a random number generator, but
  2886. it has the following properties:
  2887.  
  2888.    1) It's defined over 3D space i.e., it takes x, y, and z and returns the
  2889.       noise value there.
  2890.    2) If two points are far apart, the noise values at those points are
  2891.       relatively random.
  2892.    3) If two points are close together, the noise values at those points are
  2893.       close to each other.
  2894.  
  2895. You can visualize this as having a large room and a thermometer that ranges
  2896. from 0.0 to 1.0.  Each point in the room has a temperature.  Points that are
  2897. far apart have relatively random temperatures.  Points that are close together
  2898. have close temperatures. The temperature changes smoothly, but randomly as we
  2899. move through the room.
  2900.  
  2901. Now, let's place an object into this room along with an artist.  The artist
  2902. measures the temperature at each point on the object and paints that point a
  2903. different colour depending on the temperature.  What do we get?  BOZO texture!
  2904.  
  2905. Another function used in texturing is called DNoise.  This is sort of like
  2906. noise except that instead of giving a temperature, it gives a direction.  You
  2907. can think of it as the direction that the wind is blowing at that spot.
  2908.  
  2909. Finally, we have a function called turbulence which uses DNoise to push a
  2910. particle around a few times - each time going half as far as before.
  2911.  
  2912.          P ------------------------->
  2913.                   First Move        /
  2914.                                    /
  2915.                                   /
  2916.                                  /Second
  2917.                                 /  Move
  2918.                                /
  2919.                         ______/
  2920.                         \
  2921.                          \
  2922.                           \
  2923.                            Q - Final point.
  2924.  
  2925. This is what we use to create the "interesting" marble and wood texture.  We
  2926. locate the point we want to colour (P), then push it around a bit using
  2927. Turbulence to get to a final point (Q) then look up the colour of point Q in
  2928. our ordinary boring wood and marble textures.  That's the colour that's used
  2929. for the point P.
  2930.  
  2931. (Did you really want to know all that?  Do you really care?  I dunno.)
  2932.  
  2933. 9.5)    Layered Textures
  2934.  
  2935. As of version 2.10, DKBTrace supports layered textures.  Here's how that
  2936. works.
  2937.  
  2938. Each object and each shape has a texture that may be attached to it.  By
  2939. default, shapes have no texture, but objects have a default texture.
  2940. Internally, textures are marked as being constant or variable.  A constant
  2941. texture is one that was DECLAREd as a texture and is being shared by many
  2942. shapes and objects.  Variable textures are textures that have been declared
  2943. totally within the object or have used a DECLAREd texture and modified it in a
  2944. destructive way.  The idea here is that we want to save on memory by sharing
  2945. textures if possible. 
  2946.  
  2947. If you have several texture blocks for an object or a shape, they are placed
  2948. into a linked list (First-in Last-out).  For example, take the following
  2949. definition:
  2950.  
  2951.    OBJECT
  2952.       SPHERE <0 0 0> 1 END_SPHERE
  2953.       TEXTURE WOOD END_TEXTURE
  2954.       TEXTURE MARBLE END_TEXTURE
  2955.    END_OBJECT
  2956.  
  2957. Here's what happens while parsing this object:  Since this is an object (as
  2958. opposed to a shape - SPHERE, PLANE, etc.), it starts out with the default
  2959. texture attached.
  2960.  
  2961.    ________      _________
  2962.    |      |      |       |
  2963.    |      |----->|Default|
  2964.    |Object|      |Texture|
  2965.    |      |      |_______|
  2966.    |      |
  2967.    |______|
  2968.  
  2969. When the parser sees the first TEXTURE block, it looks to see what it has
  2970. linked.  Since the thing that's linked is the default texture (not a copy), it
  2971. discards it and puts in the new texture.
  2972.  
  2973.    ________      _________
  2974.    |      |      |       |
  2975.    |      |----->| WOOD  |
  2976.    |Object|      |Texture|
  2977.    |      |      |_______|
  2978.    |      |
  2979.    |______|
  2980.  
  2981. On the next texture, it sees that the texture isn't the default one, so it
  2982. adds the second texture into the linked list.
  2983.  
  2984.    ________      _________      _________
  2985.    |      |      |       |      |       |
  2986.    |      |----->|MARBLE |----->| WOOD  |
  2987.    |Object|      |Texture|      |Texture|
  2988.    |      |      |_______|      |_______|
  2989.    |      |
  2990.    |______|
  2991.  
  2992.  
  2993. Now for a problem.  If you want to specify the REFRACTION of the texture, the
  2994. raytracer must first calculate the surface colour.  It does this by marching
  2995. through the texture list and mixing all the colours.  When it's finished, it
  2996. checks the ALPHA value of the surface colour and decides whether it should
  2997. trace a refracting ray.  Where does it get the REFRACTION value and the index
  2998. of refraction?  It simply takes the one in the topmost (the last one defined)
  2999. texture.  I don't see any reason to have refraction values for any other
  3000. textures in the layer as it applies to the whole object.
  3001.  
  3002. 9.6)    Image Mapping
  3003.  
  3004. One major problem people have when designing data files for DKBTrace is how to
  3005. position images onto the desired surfaces.  With version 2.10, this problem
  3006. becomes slightly easier since the image can be mapped onto the object in the
  3007. object's natural coordinate system.  Thereafter, when the object is
  3008. translated, rotated, or scaled, the image map will follow it.
  3009.  
  3010. The image mapping that DKBTrace currently supports is called a "parallel
  3011. projection" mapping.  This technique is simple (that's why I implemented it
  3012. :-), but it's not perfect.  It works like a slide projector casting the
  3013. desired image onto the scene.  The difference, however, is that the image
  3014. never gets larger as you move further away from the slide projector.  In fact,
  3015. there is no real slide projector.  Consider the following cross section:
  3016.  
  3017.  
  3018. Image to Map
  3019.     |                 _________
  3020.     V                 \       /            /\        ___________________
  3021.                        \     /            /  \       \                 /
  3022. ----A-------------------A   A------------A    A-------A---------------A-->
  3023.     B                    B B            B      B       BB           BB
  3024.     C                     C            C        C        CCCC   CCCC
  3025.     D                                 D          D           DDD
  3026.     E                                E            E
  3027.     F                               F              F
  3028. ----G------------------------------G                G-------------------->
  3029.                                   /                  \
  3030.                                  /____________________\
  3031.  
  3032. This two dimensional example shows an image with colours A,B,C,D,E,F, and G
  3033. being mapped onto three objects.  The raytracer performs a similar operation
  3034. to map a 2D picture onto a 3D object.  Note that objects cannot shadow each
  3035. other from the image being mapped.  This means that the image will also appear
  3036. on the back of the object as a mirror image.
  3037.  
  3038. The mapping takes the original image (regardless of the size) and maps it onto
  3039. the range 0,0 to 1,1 in two of the 3D coordinates.  Which two coordinates is
  3040. specified by the gradient vector provided after the image.  This vector must
  3041. contain one positive number, one negative number, and one zero.  The positive
  3042. number identifies the u axis (the left-right direction in the image) and the
  3043. negative number represents the v axis (the picture's up-down direction).  Note
  3044. that the magnitude of the number is irrelevant.
  3045.  
  3046. For example:
  3047.  
  3048.     IMAGEMAP <1 -1 0> GIF "filename"
  3049.  
  3050. will map the GIF picture onto the square from <0 0 0> to <1 1 0> like this:
  3051.  
  3052.         Y
  3053.         ^
  3054.         |
  3055.         |
  3056.         |          
  3057.       1 |----------
  3058.         |   Top  R|
  3059.         |L       i|
  3060.         |e       g|
  3061.         |f       h|
  3062.         |t       t|
  3063.         | Bottom  |
  3064.         ----------------> X
  3065.                   1
  3066.  
  3067. If we reversed the vector, the picture would be transposed:
  3068.  
  3069.     IMAGEMAP <-1 1 0> GIF "filename"
  3070.  
  3071. produces:
  3072.  
  3073.         Y
  3074.         ^
  3075.         |
  3076.         |
  3077.         |          
  3078.       1 |----------
  3079.         |B Right  |
  3080.         |o       T|
  3081.         |t       o|
  3082.         |t       p|
  3083.         |o        |
  3084.         |m  Left  |
  3085.         ----------------> X
  3086.                   1
  3087.  
  3088. Once the image orientation has been determined, it can be translated, rotated,
  3089. and scaled as desired to map properly onto the object.
  3090.  
  3091.  
  3092.  
  3093. 9.7)    Output File Formats
  3094.  
  3095. People always ask me to describe the output file formats of DKBTrace.  I
  3096. received so many requests for this that I decided to put it into the document.
  3097.  
  3098. The normal "default" output format is "dump" format.  This is based on QRT
  3099. format and goes like this, where each character is a hex digit:
  3100.  
  3101. Header:
  3102.      wwww hhhh          - width, height (16 bits each, LSB first)
  3103.  
  3104. For each data line:
  3105.      llll               - line number (16 bits, LSB first, 0 to LINES-1)
  3106.      rr rr rr rr rr ... - the red components for that line
  3107.                           (8 bits each - 0=dark, 255=bright)
  3108.  
  3109.      gg gg gg gg gg ... - the green components for that line
  3110.                           (8 bits each - 0=dark, 255=bright)
  3111.  
  3112.      bb bb bb bb bb ... - the blue components for that line
  3113.                           (8 bits each - 0=dark, 255=bright)
  3114.  
  3115. Note that this format is slightly different from QRT's.
  3116.  
  3117.  
  3118. The "+fr" option of the raytracer produces "raw" files.  These are simply
  3119. three files with no header information and no line number information - just
  3120. the raw data.
  3121.  
  3122. The "+ft" option writes out Targa format.  Specifically, the fields are:
  3123.  
  3124. Header:
  3125.    00 00 02 00 00      - Fixed header information for uncompressed type 2 image
  3126.    00 00 00
  3127.    0000                - Horizontal offset always is at 0000
  3128.    llll                - Vertical offset (1st line number, 16 bits, LSB first)
  3129.    wwww hhhh           - width, height of image (16 bits each, LSB first)
  3130.    18 20               - 24 bits per pixel, Top-down raster
  3131.  
  3132. For each line:
  3133.    bb gg rr bb gg rr ... - blue, green, and red data, 8 bits for each pixel.
  3134.  
  3135.  
  3136.  
  3137.  
  3138. 10) Common Questions and Answers
  3139.  
  3140. I often get asked the same questions again and again.  I usually take this to
  3141. mean that the documentation is not complete or not sufficiently clear.  In
  3142. order to correct this problem, I've added some sections to the document
  3143. describing the features in more detail.  I've also collected some of the more
  3144. popular questions and answered them here:
  3145.  
  3146.      Q: Will you be implementing radiosity?
  3147.      A: I don't expect so.  The techniques for radiosity are quite involved
  3148.         and time consuming (although they are getting faster).  The amount of
  3149.         effort required to implement radiosity is beyond my current plans.
  3150.  
  3151.      Q: Do you intend make DKBTrace RenderMan compatible?
  3152.      A: Probably not.  RenderMan is a specification that requires much more
  3153.         functionality than DKBTrace currently provides.  The camera models,
  3154.         modelling primitives, and shading language of RenderMan are all very
  3155.         involved and difficult to implement.  As well, RenderMan is not well
  3156.         suited to a raytracing approach.  Don't expect to see DKBTrace
  3157.         RenderMan compatible in the near (or distant) future.  Note, though
  3158.         that several of the DKBTrace textures are similar to those obtainable
  3159.         by RenderMan.
  3160.  
  3161.      Q: I defined a light source but the shadows and lighting are all wrong.
  3162.      A: Light sources must be defined at the origin (0,0,0) and translated to
  3163.         the proper place.  The reason for this is to allow the diffuse lighting
  3164.         calculations to quickly determine where the center of the light source
  3165.         is.  It's a very difficult task to calculate the center of an object
  3166.         (in general), so I simply take the place that the object was translated
  3167.         to as the center of the light source.
  3168.  
  3169.      Q: I keep running out of memory.  What can I do?
  3170.      A: Buy more memory :-)  But seriously, you can decrease the memory
  3171.         requirements for any given picture in several ways:
  3172.           1) DECLARE texture constants and use them (textures are shared).
  3173.           2) Don't modify the texture that you are sharing.  On the first
  3174.              modify, the texture is copied and (therefore) takes up more space.
  3175.           3) Put the object transformations before the texture structure.  This
  3176.              prevents the texture from being transformed (and hence, copied.
  3177.              This may not always be desirable, though).
  3178.           4) Use UNIONS instead of COMPOSITE objects to put pieces together.
  3179.              (previous versions of the raytracer didn't allow this because
  3180.              the texture applied to the entire object.  Version 2.10 and up
  3181.              allow you to change the texture on a per-shape basis.)
  3182.           5) Use fewer or smaller image maps.
  3183.           6) Use GIF or IFF (non-HAM) images for image maps.  These are stored
  3184.              internally as 8 bits per pixel with a colour table instead of
  3185.              24 bits per pixel.
  3186.           
  3187.      Q: I get a floating point exception error on certain pictures. 
  3188.         What's wrong?
  3189.      A: Oh no! Not another one!  The raytracer (obviously) performs MANY
  3190.         floating point operations when tracing a scene.  If I had to check
  3191.         each one for overflow or underflow, the program would be much longer
  3192.         and I would be much closer to going insane trying to locate all
  3193.         possible cases.  If you get this problem, I'd suggest that you
  3194.         first look through your data file to make sure you're not doing
  3195.         something stupid like:
  3196.  
  3197.           - Scaling something by 0.0 in ANY dimension
  3198.           - Making the LOOK_AT point the same as the LOCATION
  3199.           - Defining triangles with two points the same (or nearly the same)
  3200.           - Using the zero vector for normals.
  3201.  
  3202.         If it doesn't seem to be one of these problems, let me know, but there
  3203.         may not be a lot I can do because overflows can occur almost anywhere.
  3204.         Sorry.  If you do have such troubles, you can try to isolate the
  3205.         problem in the input data file by commenting out objects or groups
  3206.         of objects until you narrow it down to a particular section that
  3207.         fails.  Then try commenting out the individual characteristics of the
  3208.         offending object.
  3209.  
  3210.      Q: No matter how much I scale a Cylinder, I can't make it fit on the
  3211.         screen.  How big is it and how much do I have to scale it?
  3212.      A: Cylinders (like most quadrics) are infinitely long.  No matter how
  3213.         much you scale them, they still won't fit on the screen.  To make a
  3214.         capped cylinder, you must use CSG:
  3215.  
  3216.            INTERSECTION
  3217.               QUADRIC Cylinder_Y END_QUADRIC
  3218.               PLANE <0.0 1.0 0.0> 1.0 END_PLANE
  3219.               PLANE <0.0 -1.0 0.0> 1.0 END_PLANE
  3220.            END_INTERSECTION
  3221.  
  3222.         Cylinders CAN be scaled in cross-section, the two vectors NOT in the
  3223.         name of the cylinder (X and Z, in our example above) can be scaled
  3224.         to control the width and thickness of the cylinder.  Scaling the Y
  3225.         value (which is normally infinite) is meaningless, unless you have
  3226.         "capped" it as above, then scaling the entire INTERSECTION object
  3227.         in the Y dimension will control the height of the cylinder.
  3228.  
  3229.      Q: Why don't you define a primitive for a 6-sided box?
  3230.      A: Because you can do it so easily with CSG:
  3231.  
  3232.            INTERSECTION
  3233.               PLANE < 1.0  0.0  0.0> 1.0 END_PLANE
  3234.               PLANE <-1.0  0.0  0.0> 1.0 END_PLANE
  3235.               PLANE < 0.0  1.0  0.0> 1.0 END_PLANE
  3236.               PLANE < 0.0 -1.0  0.0> 1.0 END_PLANE
  3237.               PLANE < 0.0  0.0  1.0> 1.0 END_PLANE
  3238.               PLANE < 0.0  0.0 -1.0> 1.0 END_PLANE
  3239.            END_INTERSECTION
  3240.  
  3241.      Q: Are planes 2D objects or are they 3D but infinitely thin?
  3242.      A: Neither.  Planes are 3D objects that divide the world into two
  3243.         half-spaces.  The space in the direction of the surface normal is
  3244.         considered outside and the other space is inside. In other words,
  3245.         planes are 3D objects that are infinitely thick.
  3246.  
  3247.                             ^
  3248.                             |
  3249.                             |
  3250.                             |  Outside
  3251.                      _______|_______
  3252.                                Inside
  3253.  
  3254.  
  3255.      Q: Can DKBTrace render soft shadows?
  3256.      A: No.  This would require a lot more programming work and a lot more
  3257.         calculation time.  You can place an unturbulated WOOD texture
  3258.         "filter" over a lamp in a can, and use a colour map going from dark
  3259.         (ALPHA 0.0) around the edges to clear (ALPHA 1.0) at the center,
  3260.         and get a soft-shadow-like effect for a "spotlight".
  3261.  
  3262.      Q: I'd like to go through the program and hand-optimize the assembly code
  3263.         in places to make it faster.  What should I optimize?
  3264.      A: Don't bother.  With hand optimization, you'd spend a lot of time to
  3265.         get perhaps a 5-10% speed improvement at the cost of total loss of
  3266.         portability.  If you use a better ray-surface intersection algorithm,
  3267.         you should be able to get an order of magnitude or more improvement.
  3268.         Check out some books and papers on raytracing for useful techniques.
  3269.         Specifically, check out "Spatial Subdivision" and "Ray Coherence"
  3270.         techniques.
  3271.  
  3272.      Q: Objects on the edges of the screen seem to be distorted.  Why?
  3273.      A: If the DIRECTION vector of the viewpoint is not very long, you may
  3274.         get distortion at the edges of the screen.  The reason for this is that
  3275.         the viewpoint's screen is flat:
  3276.  
  3277.  
  3278.                                | /\  This object looks small
  3279.                                | \/
  3280.                                |
  3281.                                |
  3282.                                *   <---- * = Projection of objects onto screen.
  3283.                                |
  3284.                                |
  3285.                Viewpoint --> V * /\  This object looks big
  3286.                                * \/
  3287.                                |
  3288.                                |
  3289.                                |
  3290.                                |<---- viewing screen.
  3291.                                |
  3292.                                |
  3293.  
  3294.      Q: How do you position image maps without a lot of trial and error?
  3295.      A: By default, images will be mapped onto the range 0,0 to 1,1 in the
  3296.         appropriate plane.  You should be able to translate, rotate, and
  3297.         scale the image from there.
  3298.  
  3299.      Q: What's the difference between ALPHA and REFRACTION?
  3300.      A: The difference is a bit subtle.  Alpha is a component of a colour that
  3301.         determines how much light can pass through that colour.  Refraction is
  3302.         a property of a surface that determines how much light can come from
  3303.         inside the surface.  See the section above on Transparency and
  3304.         Refraction for more details.
  3305.  
  3306.      Q: How do you calculate the surface normals for smooth triangles?
  3307.      A: When I implemented smooth triangles, I never really expected anyone to
  3308.         manually calculate the surface normals.  There are two ways of getting
  3309.         another program to calculate them for you.
  3310.  
  3311.           1) Depending on the type of input to the program, you may be able to
  3312.              calculate the surface normals directly.  For example, if you have
  3313.              a program that converts B-Spline or Bezier Spline surfaces into
  3314.              DKB-format files, you can calculate the surface normals from the
  3315.              surface equations.
  3316.  
  3317.           2) If your original data was a polygon or triangle mesh, then it's
  3318.              not quite so simple.  You have to first calculate the surface
  3319.              normals of all the triangles.  This is easy to do - you just use
  3320.              the vector cross-product of two sides (make sure you get the
  3321.              vectors in the right order).  Then, for every vertex, you average
  3322.              the surface normals of the triangles that meet at that vertex.
  3323.              These are the normals you use for smooth triangles.
  3324.  
  3325.      Q: When I render parts of a picture on different systems, the textures
  3326.         don't match when I put them together.  Why?
  3327.      A: The appearance of a texture depends on the particular random number
  3328.         generator used on your system.  DKBTrace seeds the random number
  3329.         generator with a fixed value when it starts, so the textures will be
  3330.         consistent from one run to another or from one frame to another so
  3331.         long as you use the same executables.  Once you change executables,
  3332.         you will likely change the random number generator and, hence, the
  3333.         appearance of the texture.  There is an example of a standard ANSI
  3334.         random number generator provided in IBM.C, include it in your machine-
  3335.         specific code if you are having consistency problems.
  3336.  
  3337.      Q: What's the difference between a COLOUR declared inside a TEXTURE
  3338.         and one that's in a shape or an object and not in a texture?
  3339.      A: The colour in the texture specifies the colour to use for qualities
  3340.         5 and up.  The colour on the shape and object are used for faster
  3341.         rendering in qualities 4 and lower and for the colour of light sources.
  3342.         See the -q option for details on the quality parameter.
  3343.  
  3344.  
  3345.      Q: I created an object that passes through its bounding volume.  At times,
  3346.         I can see the parts of the object that are outside the bounding volume.
  3347.         Why does this happen?
  3348.      A: Bounding volumes are NOT designed to change the shape of the object.
  3349.         They are strictly a realtime improvement feature.  The raytracer trusts
  3350.         you when you say that the object is enclosed by a bounding volume.  The
  3351.         way it uses bounding volumes is very simple:  If the ray hits the
  3352.         bounding volume (or the ray's origin is inside the bounding volume),
  3353.         then the object is tested against that ray.  Otherwise, we ignore the
  3354.         object.  If the object extends beyond the bounding volume, anything goes.
  3355.         The results are undefined.  It's quite possible that you could see the
  3356.         object outside the bounding volume and it's also possible that it could
  3357.         be invisible.  It all depends on the geometry of the scene.
  3358.  
  3359.      Q: Will you be writing a Graphical User Interface for DKB?
  3360.      A: No, but several other people have expressed an interest in writing
  3361.         one.  I'd like to form a mailing list to get all these people in touch
  3362.         with each other, so if you have an interest in this, please let me
  3363.         know.
  3364.  
  3365.      Q: When will the next version be available?
  3366.      A: If I told you, I'd be lying because I don't know.  I'm finding that
  3367.         releasing an official version of a program like this is a major
  3368.         effort.  It requires not only the changes to the code, but also
  3369.         changes to the documentation.  Sometimes (as with this release), I
  3370.         have to change the older data files to conform to the new syntax.
  3371.         Usually, I have to spend a lot of time re-rendering scenes that used
  3372.         to work to make sure they still do.  That combined with sending the
  3373.         files to beta testers, getting feedback, making fixes, and re-issuing
  3374.         the changes adds up to a lot of work.  I don't expect I'll be doing
  3375.         it terribly often.
  3376.  
  3377.         Bottom line - If I say "next week", don't believe me.  I'm probably
  3378.         wrong.
  3379.  
  3380.  
  3381.  
  3382. 11) Converting Data Files from Versions Prior to 2.10
  3383.  
  3384. Unfortunately, version 2.10 changed the format of the data files.  These
  3385. changes were mostly to avoid confusion - especially in the case of layered
  3386. textures.  There were also some changes that were made to allow more flexible
  3387. library objects.  This section details the changes in the data file format and
  3388. why it was necessary to make those changes.  I'm sorry that you have to go
  3389. back through all your old data files and edit them all, but I think you'll
  3390. agree (I hope you'll agree :-) that the changes are for the better.
  3391.  
  3392.    1) The following keywords are no longer accepted outside of a TEXTURE block:
  3393.         AMBIENT, DIFFUSE, BRILLIANCE, REFLECTION, REFRACTION, IOR, PHONG,
  3394.         PHONG_SIZE, SPECULAR, ROUGHNESS
  3395.  
  3396.       Reason: For layered textures, it's not clear which texture these keywords
  3397.               apply to if they're not in a TEXTURE block.  I was really getting
  3398.               messed up in the implementation trying to locate the proper
  3399.               references for these keywords.  It's much cleaner to only allow
  3400.               them inside a TEXTURE block.
  3401.  
  3402.    2) A new texture called COLOUR (or COLOR) has been added.  This texture
  3403.       simply specifies a simple colour to use.
  3404.  
  3405.       Reason:  It's useful to be able to declare a TEXTURE with the colour
  3406.                embedded inside it.  Besides, I had to provide some way of
  3407.                specifying a simple colour after I made the following change:
  3408.  
  3409.    3) The keyword "COLOUR" or "COLOR" when used outside of a TEXTURE block
  3410.       is only used to provide a colour for low-quality renderings (ones where
  3411.       the -q value is 5 or below.
  3412.  
  3413.       Reason:  This is the same reason as for change 1.  For layered textures,
  3414.                it wasn't clear what the object or shape colour meant when the
  3415.                texture itself contained colour information.  Rather than have
  3416.                a convoluted searching scheme (which I tried at first, then
  3417.                abandoned due to difficulties in explaining it), I decided to
  3418.                keep it simple.  If you want a simple colour, put it in a
  3419.                TEXTURE block.
  3420.  
  3421.    4) When an object or shape is transformed, the textures attached to it are
  3422.       transformed as well.
  3423.  
  3424.       Reason:  Previously, you couldn't DECLARE objects with textures, then
  3425.                create identical copies of them in different places.  This was
  3426.                especially annoying when you create an object that has an image
  3427.                mapped onto it.  As soon as you moved the object, the image was
  3428.                left behind.  Unfortunately, this means that the texture trans-
  3429.                formations inside TEXTURE blocks in old data files would double
  3430.                transform the texture, and must be removed.
  3431.  
  3432.    5) The interaction between ALPHA colours and REFRACTION has changed.
  3433.       Previously, there was no interaction at all.  If you had a surface that
  3434.       contained an ALPHA colour, you could see through the surface.  If the
  3435.       surface had refraction, you could also see through.  With the new
  3436.       release, ALPHA and REFRACTION in combination tell you how much light
  3437.       is passed through from the inside of the object.
  3438.  
  3439.       To make things a bit easier, if an object has an ALPHA component but the
  3440.       REFRACTION is 0.0 (or unspecified), the renderer will simply transmit the
  3441.       ray through the object without any refractive bending.
  3442.  
  3443.       Reason:  It seemed to make sense.  The code for ALPHA was doing the same
  3444.                work as the code for REFRACTION except for actually bending
  3445.                the ray.  Now, you can create objects that are partially opaque
  3446.                and partially transparent. Where they are transparent, the light
  3447.                passing through the object is bent by the index of refraction.
  3448.                Makes sense, no?
  3449.  
  3450.    6) When you use an IMAGEMAP with the ONCE option, the colour outside the
  3451.       mapped image is transparent (RED 1.0 GREEN 1.0 BLUE 1.0 ALPHA 1.0).
  3452.  
  3453.       Reason:  This allows you to see the underlying textures.
  3454.  
  3455.  
  3456.    7) I've remove "BasicShapes.data" and replaced it with "shapes.dat",
  3457.       "colors.dat", and "textures.dat".
  3458.  
  3459.  
  3460.       Reason:  The old name didn't apply any more (since it contained more than
  3461.                just shapes).  Also, I was tired of the IBM people using the
  3462.                name "BASICSHA.DAT" :-).
  3463.  
  3464.    8) The textures in textures.dat (formerly BasicShapes.data) were previously
  3465.       scaled to <10.0 10.0 10.0>.  This scaling has been removed.
  3466.  
  3467.       Reason:  The factor of 10.0 seemed to be a totally arbitrary scale factor
  3468.                that someone used.  I'd like to keep the scaling factors up to
  3469.                the users.
  3470.  
  3471. 12) Handy Hints
  3472.  
  3473.      -    To see a quick version of your picture, use -w64 -h80 as command
  3474.           line parameters on the Amiga.  For the IBM, try -w80 -h50.  This
  3475.           displays the picture in a small rectangle so that you can see how
  3476.           it will look.
  3477.  
  3478.      -    Try using the sample default files for different usages - QUICK.DEF
  3479.           shows a fast postage-stamp rendering (80x50, as above) to the
  3480.           screen only, LOCKED.DEF will display the picture with anti-aliasing
  3481.           on (takes forever) with no abort (do this before you go to bed...).
  3482.           The normal default options file TRACE.DEF is read and you can
  3483.           supersede this with another .DEF file by specifying it on the
  3484.           command line, for example:
  3485.  
  3486.           trace -iworld.dat -oworld.out quick.def
  3487.  
  3488.      -    When translating light sources, translate the OBJECT, not the
  3489.           QUADRIC surface.  The light source uses the center of the object as
  3490.           the origin of the light.
  3491.  
  3492.      -    When animating objects with solid textures, the textures must move
  3493.           with the object, i.e. apply the same ROTATE or TRANSLATE functions
  3494.           to the texture as to the object itself.  This is now done automatic-
  3495.           ally in version 2.10 if the transformations are placed _after_ the
  3496.           TEXTURE block.
  3497.  
  3498.      -    You can declare constants for most of the data types in the program
  3499.           including floats and vectors.  By combining this with INCLUDE files,
  3500.           you can easily separate the parameters for an animation into a
  3501.           separate file.
  3502.  
  3503.      -    The amount of ambient light plus diffuse light should be less than
  3504.           or equal to 1.0.  The program accepts any values, but may produce
  3505.           strange results.
  3506.  
  3507.      -    When using ripples, don't make the ripples too deep or you may get
  3508.           strange results (the dreaded "digital zits"!).
  3509.  
  3510.      -    Wood textures usually look better when they are scaled to different
  3511.           values in x, y, and z, and then rotated to a different angle.
  3512.  
  3513.      -    You can sort of dither a colour by placing a floating point number
  3514.           into the texture record:
  3515.  
  3516.           TEXTURE
  3517.                0.05
  3518.           END_TEXTURE
  3519.  
  3520.           This adds a small random value to the intensity of the diffuse
  3521.           light on the object.  Don't make the number too big or you may get
  3522.           strange results.  You generally won't want to use this if you are
  3523.           rendering frames for animations, as this "dithering" is random.
  3524.  
  3525.           Better results can be obtained, however, by doing proper dithering
  3526.           in a post-processor.
  3527.  
  3528.      -    You can compensate for non-square aspect ratios on the monitors by
  3529.           making the RIGHT vector in the VIEWPOINT longer or shorter.  A good
  3530.           value for the Amiga is about 1.333.  This seems ok for IBM's too at
  3531.           320x200 resolution.  If your spheres and circles aren't round, try
  3532.           varying it.
  3533.  
  3534.      -    If you are importing images from other systems, you may find that
  3535.           the shapes are backwards (left-to-right inverted) and no rotation
  3536.           can make them right.  All you have to do is negate the terms in the
  3537.           RIGHT vector of the viewpoint to flip the camera left-to-right (use
  3538.           the "right-hand" coordinate system).
  3539.  
  3540.      -    By making the DIRECTION vector in the VIEWPOINT longer, you can
  3541.           achieve the effect of a tele-photo lens.
  3542.  
  3543.      -    When rendering on the Amiga, use a resolution of 320 by 400 to
  3544.           create a full sized HAM picture.
  3545.  
  3546.  
  3547.  
  3548. 13) Compiling the Code
  3549.  
  3550. If you want to compile the source code on a supported platform, do the
  3551. following:
  3552.  
  3553.     1) Copy or rename the file called <system>conf.h to config.h
  3554.          eg.  rename amigaconf.h config.h
  3555.  
  3556.     2) Copy or rename the appropriate make file to "makefile"
  3557.          eg.  rename amigamake makefile
  3558.  
  3559.     3) Edit the makefile to make sure all compiler options are set up
  3560.          properly for your system.
  3561.  
  3562.     4) Type "make"
  3563.  
  3564.  
  3565.  
  3566.  
  3567. 14) Porting to Different Platforms
  3568.  
  3569. I've taken great pains to make DKBTrace as portable as possible.  So far, it's
  3570. working out fairly well.  For the most part, the core of the raytracer will
  3571. compile with any decent C compiler.
  3572.  
  3573. If you want to port the raytracer to another system, please try to modify the
  3574. core of the raytracer as little as possible.  Each system will have its own
  3575. makefile, config file, and C file.  The config file is included by all of the
  3576. raytrace modules and can be used to perform special #defines for that system.
  3577. The C file should contain all system-specific code.  It must implement the
  3578. following functions:
  3579.  
  3580.    void display_init ();    /* Open the graphics device and initialize it */
  3581.    void display_close();    /* Close the graphics device                  */
  3582.    void display_finished(); /* Perform any operations required after      */
  3583.                             /* finishing the rendering but before quitting*/
  3584.    void display_plot (x, y, Red, Green, Blue)
  3585.                             /* Display the specified colour at point x,y  */
  3586.  
  3587.  
  3588. In your config file, you may customize the following things:
  3589.  
  3590.    #define FILE_NAME_LENGTH    (default 150)
  3591.    #define DBL_FORMAT_STRING   (the string to use to read a double)
  3592.    #define DEFAULT_OUTPUT_FORMAT ('d', 'r' or 't' - default output file format)
  3593.    #define TEST_ABORT          (the operation to perform while tracing to see
  3594.                                 if we should abort the trace.)
  3595.    #define RED_RAW_FILE_EXTENSION
  3596.    #define GREEN_RAW_FILE_EXTENSION
  3597.    #define BLUE_RAW_FILE_EXTENSION
  3598.                                (the default extensions for the +fr mode)
  3599.  
  3600.    #define STARTUP_DKB_TRACE   (the code to call immediately after starting
  3601.                                 the main program. - useful if you don't have
  3602.                                 a command-line interface)
  3603.  
  3604.    #define PARAMS(x)           ("(x)" if you have prototypes, "()" otherwise)
  3605.  
  3606.  
  3607.  
  3608. 15) References
  3609.  
  3610. I'm always asked about good books on raytracing and graphics in general.
  3611. This section address that issue by listing several good books or periodicals
  3612. that you should be able to locate in your local computer book store or your
  3613. local university library.
  3614.  
  3615.     "An Introduction to Raytracing"
  3616.     Andrew S. Glassner (editor)
  3617.     Academic Press
  3618.     1989
  3619.  
  3620.     "Image Synthesis:  Theory and Practice"
  3621.     Nadia Magnenat-Thalman and Daniel Thalmann
  3622.     Springer-Verlag
  3623.     1987
  3624.  
  3625.     "The RenderMan Companion"
  3626.     Steve Upstill
  3627.     Addison Wesley
  3628.     1989
  3629.  
  3630.     "Graphics Gems"
  3631.     Andrew S. Glassner (editor)
  3632.     Academic Press
  3633.     1990
  3634.  
  3635.     "Fundamentals of Interactive Computer Graphics"
  3636.     J. D. Foley and A. Van Dam
  3637.     Addison-Wesley
  3638.     1983
  3639.  
  3640.     "Computer Graphics:  Principles and Practice (2nd Ed.)"
  3641.     J. D. Foley, A. van Dam, J. F. Hughes
  3642.     Addison-Wesley,
  3643.     1990
  3644.  
  3645.     "Computers, Pattern, Chaos, and Beauty"
  3646.     Clifford Pickover
  3647.     St. Martin's Press
  3648.  
  3649.     "SIGGRAPH Conference Proceedings"
  3650.     Association for Computing Machinery
  3651.     Special Interest Group on Computer Graphics
  3652.  
  3653.     "IEEE Computer Graphics and Applications"
  3654.     The Computer Society
  3655.     10662, Los Vaqueros Circle
  3656.     Los Alimitos, CA 90720
  3657.  
  3658.     "The CRC Handbook of Mathematical Curves and Surfaces"
  3659.     David von Seggern
  3660.     CRC Press
  3661.     1990
  3662.  
  3663.     "The CRC Handbook of Standard Mathematical Tables"
  3664.     CRC Press
  3665.     The Beginning of Time
  3666.  
  3667.  
  3668. 16) Concluding Remarks
  3669.  
  3670. It seems that in any project like this, as soon as you fix some bugs, some
  3671. more appear.  I expect that the new features I provided in this release will
  3672. cause some problems somewhere.  There's only so much you can do to get all the
  3673. bugs out.  For the next little while, I intend to keep the program stable
  3674. feature-wise and just tackle major bugs.  Hopefully things will stablize this
  3675. way (and I can take a much needed breather).
  3676.  
  3677. Thanks go out to Alexander Enzmann for generously providing the code for the
  3678. QUARTIC surface algorithms, and for his assistance in implementing it and
  3679. for helping squash a couple of other bugs.
  3680.  
  3681. I would like to thank all the people who used versions 2.01 and 2.04 and
  3682. provided useful comments and helpful suggestions.  The program has been much
  3683. improved with your help.
  3684.  
  3685. I would also like to thank my beta testers for all the help, bug reports,
  3686. suggestions, comments, and time spent.  I'd like to say a special thank-you to
  3687. Aaron Collins who has fielded many of the questions on the raytracer and has
  3688. been invaluable in debugging, testing, and generally improving the program.
  3689. Thanks guys. 
  3690.  
  3691. David Buck
  3692.  
  3693.